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.
Syntax
class agent;
Members
Public Constructors
| Name | Description |
|---|---|
| agent | Overloaded. Constructs an agent. |
| ~agent Destructor | Destroys the agent. |
Public Methods
| 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. |
Protected Methods
| 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. |
Remarks
For more information, see Asynchronous Agents.
Inheritance Hierarchy
agent
Requirements
Header: agents.h
Namespace: concurrency
agent
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.
~agent
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.
cancel
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.
done
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.
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.
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.
start
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.
status
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.
status_port
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.
wait
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.
wait_for_all
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.
wait_for_one
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.