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. More...

#include <agents.h>

Public Member Functions
_CRTIMP2	agent ()
	Constructs an agent. More...

virtual _CRTIMP2	~agent ()
	Destroys the agent. More...

_CRTIMP2 ISource< agent_status > *	status_port ()
	An asynchronous source of status information from the agent. More...

_CRTIMP2 agent_status	status ()
	A synchronous source of status information from the agent. More...

_CRTIMP2 bool	start ()
	Moves an agent from the `agent_created` state to the `agent_runnable` state, and schedules it for execution. More...

_CRTIMP2 bool	cancel ()
	Moves an agent from either the `agent_created` or `agent_runnable` states to the `agent_canceled` state. More...

Static Public Member Functions
static _CRTIMP2 agent_status __cdecl	wait (_Inout_ agent *_PAgent, unsigned int _Timeout=COOPERATIVE_TIMEOUT_INFINITE)
	Waits for an agent to complete its task. More...

static _CRTIMP2 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)
	Waits for all of the specified agents to complete their tasks. More...

static _CRTIMP2 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)
	Waits for any one of the specified agents to complete its task. More...

Protected Member Functions
virtual void	run ()=0
	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. More...

_CRTIMP2 bool	done ()
	Moves an agent into the `agent_done` state, indicating that the agent has completed. More...

Protected Attributes
overwrite_buffer< agent_status >	_M_status
	Holds the current status of the agent. More...

Private Member Functions
agent const &	operator= (agent const &)

	agent (agent const &)

Static Private Member Functions
static void __cdecl	_Agent_task_wrapper (void *data)

Private Attributes
volatile long	_M_fStartable

volatile long	_M_fCancelable

Scheduler *	_M_pScheduler

ScheduleGroup *	_M_pScheduleGroup

Detailed Description

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.

For more information, see Asynchronous Agents.

Constructor & Destructor Documentation

_CRTIMP2 Concurrency::agent::agent ( )

Constructs an agent.

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

See also: Scheduler Class, ScheduleGroup Class

virtual _CRTIMP2 Concurrency::agent::~agent ( )

virtual

Destroys the 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.

Concurrency::agent::agent ( agent const & )

private

Member Function Documentation

static void __cdecl Concurrency::agent::_Agent_task_wrapper ( void * data )

staticprivate

_CRTIMP2 bool Concurrency::agent::cancel ( )

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

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

See also: agent_status Enumeration

_CRTIMP2 bool Concurrency::agent::done ( )

protected

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

Returns: 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.

See also: agent_status Enumeration

agent const& Concurrency::agent::operator= ( agent const & )

private

virtual void Concurrency::agent::run ( )

protectedpure virtual

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.

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.

_CRTIMP2 bool Concurrency::agent::start ( )

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

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

See also: agent_status Enumeration

_CRTIMP2 agent_status Concurrency::agent::status ( )

A synchronous source of status information from the agent.

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

See also: agent_status Enumeration

_CRTIMP2 ISource<agent_status>* Concurrency::agent::status_port ( )

An asynchronous source of status information from the agent.

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

static _CRTIMP2 agent_status __cdecl Concurrency::agent::wait	(	_Inout_ agent *	_PAgent,
		unsigned int	_Timeout = `COOPERATIVE_TIMEOUT_INFINITE`
	)

static

Waits for an agent to complete its task.

Parameters

_PAgent	A pointer to the agent to wait for.
_Timeout	The maximum time for which to wait, in milliseconds.

Returns: 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.

See also: agent::wait_for_all Method, agent::wait_for_one Method, agent_status Enumeration

static _CRTIMP2 void __cdecl Concurrency::agent::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`
	)

static

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

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.

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.

See also: agent::wait Method, agent::wait_for_one Method, agent_status Enumeration

static _CRTIMP2 void __cdecl Concurrency::agent::wait_for_one	(	size_t	_Count,
		_In_reads_(_Count) agent **	_PAgents,
		agent_status &	_Status,
		size_t &	_Index,
		unsigned int	_Timeout = `COOPERATIVE_TIMEOUT_INFINITE`
	)

static

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

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.

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.

See also: agent::wait Method, agent::wait_for_all Method, agent_status Enumeration

Member Data Documentation

volatile long Concurrency::agent::_M_fCancelable

private

volatile long Concurrency::agent::_M_fStartable

private

ScheduleGroup* Concurrency::agent::_M_pScheduleGroup

private

Scheduler* Concurrency::agent::_M_pScheduler

private

overwrite_buffer<agent_status> Concurrency::agent::_M_status

protected

Holds the current status of the agent.

The documentation for this class was generated from the following file:

VS2013/inc/agents.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation