agent Class
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;
| Name | Description |
|---|---|
| agent | Overloaded. Constructs an agent. |
| ~agent Destructor | Destroys the agent. |
| Name | Description |
|---|---|
| cancel | Moves an agent from either the agent_created or agent_runnable states to the agent_canceled state. |
| start | Moves an agent from the agent_created state to the agent_runnable state, and schedules it for execution. |
| status | A synchronous source of status information from the agent. |
| status_port | An asynchronous source of status information from the agent. |
| wait | Waits for an agent to complete its task. |
| wait_for_all | Waits for all of the specified agents to complete their tasks. |
| wait_for_one | Waits for any one of the specified agents to complete its task. |
| Name | Description |
|---|---|
| done | Moves an agent into the agent_done state, indicating that the agent has completed. |
| run | 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. |
For more information, see Asynchronous Agents.
agent
Header: agents.h
Namespace: concurrency
Constructs an agent.
agent();
agent(Scheduler& _PScheduler);
agent(ScheduleGroup& _PGroup);
_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.
The runtime uses the default scheduler if you do not specify the _PScheduler or _PGroup parameters.
Destroys the agent.
virtual ~agent();
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();
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();
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.
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;
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();
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();
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();
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);
_PAgent
A pointer to the agent to wait for.
_Timeout
The maximum time for which to wait, in milliseconds.
The agent_status of the agent when the wait completes. This can either be agent_canceled or agent_done.
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);
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.
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);
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.
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.