description | title | ms.date | helpviewer_keywords | ms.assetid | ||
---|---|---|---|---|---|---|
Learn more about: Asynchronous Agents |
Asynchronous Agents |
11/19/2018 |
|
6cf6ccc6-87f1-4e14-af15-ea8ba58fef1a |
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 agent
.
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 agent_status
enumeration.
Agent State | Description |
---|---|
agent_created |
The agent has not been scheduled for execution. |
agent_runnable |
The runtime is scheduling the agent for execution. |
agent_started |
The agent has started and is running. |
agent_done |
The agent finished. |
agent_canceled |
The agent was canceled before it entered the started state. |
agent_created
is the initial state of an agent, agent_runnable
and agent_started
are the active states, and agent_done
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.
Method | Description |
---|---|
start | Schedules the agent object for execution and sets it to the agent_runnable state. |
run | Executes the task that is to be performed by the agent object. |
done | Moves an agent to the agent_done state. |
cancel | If the agent was not started, this method cancels execution of the agent and sets it to the agent_canceled state. |
status | Retrieves the current state of the agent object. |
wait | Waits for the agent object to enter the agent_done or agent_canceled state. |
wait_for_all | Waits for all provided agent objects to enter the agent_done or agent_canceled state. |
wait_for_one | Waits for at least one of the provided agent objects to enter the agent_done or agent_canceled state. |
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 agent_runnable
state.
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.