For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
An asynchronous agent (or just agent) is an application component that works asynchronously with other agents to solve larger computing tasks. Think of an agent as a task that has a set life cycle. For example, one agent might read data from an input/output device (such as the keyboard, a file on disk, or a network connection) and another agent might perform action on that data as it becomes available. The first agent uses message passing to inform the second agent that more data is available. The Concurrency Runtime task scheduler provides an efficient mechanism to enable agents to block and yield cooperatively without requiring less efficient preemption.
The Agents Library defines the concurrency::agent class to represent an asynchronous agent.
agent is an abstract class that declares the virtual method concurrency::agent::run. The
run method executes the task that is performed by the agent. Because
run is abstract, you must implement this method in every class that you derive from
Agents have a set life cycle. The concurrency::agent_status enumeration defines the various states of an agent. The following illustration is a state diagram that shows how agents progress from one state to another. In this illustration, solid lines represent methods that you call from your application; dotted lines represent methods that are called from the runtime.
The following table describes each state in the
|The agent has not been scheduled for execution.|
|The runtime is scheduling the agent for execution.|
|The agent has started and is running.|
|The agent finished.|
|The agent was canceled before it entered the |
agent_created is the initial state of an agent,
agent_started are the active states, and
agent_canceled are the terminal states.
Use the concurrency::agent::status method to retrieve the current state of an
agent object. Although the
status method is concurrency-safe, the state of the agent can change by the time the
status method returns. For example, an agent could be in the
agent_started state when you call the
status method, but moved to the
agent_done state just after the
status method returns.
The following table shows some of the important methods that belong to the
agent class. For more information about all of the
agent class methods, see agent Class.
|start||Schedules the |
|run||Executes the task that is to be performed by the |
|done||Moves an agent to the |
|cancel||If the agent was not started, this method cancels execution of the agent and sets it to the |
|status||Retrieves the current state of the |
|wait||Waits for the |
|wait_for_all||Waits for all provided |
|wait_for_one||Waits for at least one of the provided |
After you create an agent object, call the concurrency::agent::start method to schedule it for execution. The runtime calls the
run method after it schedules the agent and sets it to the
The runtime does not manage exceptions that are thrown by asynchronous agents. For more information about exception handling and agents, see Exception Handling.
For an example that shows how to create a basic agent-based application, see Walkthrough: Creating an Agent-Based Application.