agent Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

A class intended to be used as a base class for all independent agents. It is used to hide state from other agents and interact using message-passing.

class agent;

Public Constructors

NameDescription
agent::agent ConstructorOverloaded. Constructs an agent.
agent::~agent DestructorDestroys the agent.

Public Methods

NameDescription
agent::cancel MethodMoves an agent from either the agent_created or agent_runnable states to the agent_canceled state.
agent::start MethodMoves an agent from the agent_created state to the agent_runnable state, and schedules it for execution.
agent::status MethodA synchronous source of status information from the agent.
agent::status_port MethodAn asynchronous source of status information from the agent.
agent::wait MethodWaits for an agent to complete its task.
agent::wait_for_all MethodWaits for all of the specified agents to complete their tasks.
agent::wait_for_one MethodWaits for any one of the specified agents to complete its task.

Protected Methods

NameDescription
agent::done MethodMoves an agent into the agent_done state, indicating that the agent has completed.
agent::run MethodRepresents the main task of an agent. run should be overridden in a derived class, and specifies what the agent should do after it has been started.

For more information, see Asynchronous Agents.

agent

Header: agents.h

Namespace: concurrency

Constructs an agent.

agent();

agent(Scheduler& _PScheduler);

agent(ScheduleGroup& _PGroup);

Parameters

_PScheduler
The Scheduler object within which the execution task of the agent is scheduled.

_PGroup
The ScheduleGroup object within which the execution task of the agent is scheduled. The Scheduler object used is implied by the schedule group.

Remarks

The runtime uses the default scheduler if you do not specify the _PScheduler or _PGroup parameters.

Destroys the agent.

virtual ~agent();

Remarks

It is an error to destroy an agent that is not in a terminal state (either agent_done or agent_canceled). This can be avoided by waiting for the agent to reach a terminal state in the destructor of a class that inherits from the agent class.

Moves an agent from either the agent_created or agent_runnable states to the agent_canceled state.

bool cancel();

Return Value

true if the agent was canceled, false otherwise. An agent cannot be canceled if it has already started running or has already completed.

Moves an agent into the agent_done state, indicating that the agent has completed.

bool done();

Return Value

true if the agent is moved to the agent_done state, false otherwise. An agent that has been canceled cannot be moved to the agent_done state.

Remarks

This method should be called at the end of the run method, when you know the execution of your agent has completed.

Represents the main task of an agent. run should be overridden in a derived class, and specifies what the agent should do after it has been started.

virtual void run() = 0;

Remarks

The agent status is changed to agent_started right before this method is invoked. The method should invoke done on the agent with an appropriate status before returning, and may not throw any exceptions.

Moves an agent from the agent_created state to the agent_runnable state, and schedules it for execution.

bool start();

Return Value

true if the agent started correctly, false otherwise. An agent that has been canceled cannot be started.

A synchronous source of status information from the agent.

agent_status status();

Return Value

Returns the current state of the agent. Note that this returned state could change immediately after being returned.

An asynchronous source of status information from the agent.

ISource<agent_status>* status_port();

Return Value

Returns a message source that can send messages about the current state of the agent.

Waits for an agent to complete its task.

static agent_status __cdecl wait(
    _Inout_ agent* _PAgent,
    unsigned int _Timeout = COOPERATIVE_TIMEOUT_INFINITE);

Parameters

_PAgent
A pointer to the agent to wait for.

_Timeout
The maximum time for which to wait, in milliseconds.

Return Value

The agent_status of the agent when the wait completes. This can either be agent_canceled or agent_done.

Remarks

An agent task is completed when the agent enters the agent_canceled or agent_done states.

If the parameter _Timeout has a value other than the constant COOPERATIVE_TIMEOUT_INFINITE, the exception operation_timed_out is thrown if the specified amount of time expires before the agent has completed its task.

Waits for all of the specified agents to complete their tasks.

static void __cdecl wait_for_all(
    size_t count,
    _In_reads_(count) agent** _PAgents,
    _Out_writes_opt_(count) agent_status* _PStatus = NULL,
    unsigned int _Timeout = COOPERATIVE_TIMEOUT_INFINITE);

Parameters

count
The number of agent pointers present in the array _PAgents.

_PAgents
An array of pointers to the agents to wait for.

_PStatus
A pointer to an array of agent statuses. Each status value will represent the status of the corresponding agent when the method returns.

_Timeout
The maximum time for which to wait, in milliseconds.

Remarks

An agent task is completed when the agent enters the agent_canceled or agent_done states.

If the parameter _Timeout has a value other than the constant COOPERATIVE_TIMEOUT_INFINITE, the exception operation_timed_out is thrown if the specified amount of time expires before the agent has completed its task.

Waits for any one of the specified agents to complete its task.

static void __cdecl wait_for_one(
    size_t count,
    _In_reads_(count) agent** _PAgents,
    agent_status& _Status,
    size_t& _Index,
    unsigned int _Timeout = COOPERATIVE_TIMEOUT_INFINITE);

Parameters

count
The number of agent pointers present in the array _PAgents.

_PAgents
An array of pointers to the agents to wait for.

_Status
A reference to a variable where the agent status will be placed.

_Index
A reference to a variable where the agent index will be placed.

_Timeout
The maximum time for which to wait, in milliseconds.

Remarks

An agent task is completed when the agent enters the agent_canceled or agent_done states.

If the parameter _Timeout has a value other than the constant COOPERATIVE_TIMEOUT_INFINITE, the exception operation_timed_out is thrown if the specified amount of time expires before the agent has completed its task.

concurrency Namespace

Show: