Concurrency Namespace

Article
02/04/2013

The Concurrency namespace provides classes and functions that give you access to the Concurrency Runtime, a concurrent programming framework for C++. For more information, see Concurrency Runtime.

namespace Concurrency;

Members

Typedefs

Name	Description
runtime_object_identity	Each message instance has an identity that follows it as it is cloned and passed between messaging components. This cannot be the address of the message object.
TaskProc	An elementary abstraction for a task, defined as *void (__cdecl TaskProc)(void ). A TaskProc* is called to invoke the body of a task.

Classes

Name	Description
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 via message-passing.
bad_target Class	This class describes an exception that is thrown whenever a messaging block is given a pointer to a target which is invalid for the operation being performed.
call Class	A call messaging block is a multi-source, ordered target_block that invokes a specified function when receiving a message.
choice Class	A choice messaging block is a multi-source, single-target block that represents a control-flow interaction with a set of sources. The choice block will wait for any one of multiple sources to produce a message and will propagate the index of the source that produced the message.
combinable Class	The combinable<T> object is intended to provide thread-private copies of data, to perform lock-free thread-local sub-computations during parallel algorithms. At the end of the parallel operation, the thread-private sub-computations can then be merged into a final result. This class can be used instead of a shared variable, and can result in a performance improvement if there would otherwise be a lot of contention on that shared variable.
concurrent_queue Class	The concurrent_queue class is a sequence container class that allows first-in, first-out access to its elements. It enables a limited set of concurrency-safe operations, such as push and try_pop, to name a few.
concurrent_vector Class	The concurrent_vector class is a sequence container class that allows random access to any element. It enables concurrency-safe append, element access, iterator access and iterator traversal operations.
Context Class	Represents an abstraction for an execution context.
context_self_unblock Class	This class describes an exception that is thrown whenever the Unblock method of a Context object is called from the same context. This would indicate an attempt by a given context to unblock itself.
context_unblock_unbalanced Class	This class describes an exception that is thrown whenever calls to the Block and Unblock methods of a Context object are not properly paired.
critical_section Class	A non-reentrant mutex which is explicitly aware of the Concurrency Runtime.
CurrentScheduler Class	Represents an abstraction for the current scheduler associated with the calling context.
default_scheduler_exists Class	This class describes an exception that is thrown whenever the Scheduler::SetDefaultSchedulerPolicy method is called when a default scheduler already exists within the process.
event Class (Concurrency Runtime)	A manual reset event which is explicitly aware of the Concurrency Runtime.
improper_lock Class	This class describes an exception that is thrown whenever a lock is acquired improperly.
improper_scheduler_attach Class	This class describes an exception that is thrown whenever the Attach method is called on a Scheduler object which is already attached to the current context.
improper_scheduler_detach Class	This class describes an exception that is thrown whenever the CurrentScheduler::Detach method is called on a context which has not been attached to any scheduler via the Attach method of a Scheduler object.
improper_scheduler_reference Class	This class describes an exception that is thrown whenever the Reference method is called on a Scheduler object that is shutting down, from a context that is not part of that scheduler.
invalid_link_target Class	This class describes an exception that is thrown whenever the link_target method of a messaging block is called and the messaging block is unable to link to the target. This may be the result of exceeding the number of links the messaging block is allowed or attempting to link a specific target twice to the same source.
invalid_multiple_scheduling Class	This class describes an exception that is thrown when a task_handle object is scheduled multiple times via the run method of a task_group or structured_task_group object without an intervening call to either the wait or run_and_wait methods.
invalid_operation Class	This class describes an exception that is thrown when an invalid operation is performed that is not more accurately described by another exception type thrown by the Concurrency Runtime.
invalid_oversubscribe_operation Class	This class describes an exception that is thrown when the Context::Oversubscribe method is called with the _BeginOversubscription parameter set to false without a prior call to the Context::Oversubscribe method with the _BeginOversubscription parameter set to true.
invalid_scheduler_policy_key Class	This class describes an exception that is thrown whenever an invalid or unknown key is passed to a SchedulerPolicy object constructor, or the SetPolicyValue method of a SchedulerPolicy object is passed a key that must be changed via other means such as the SetConcurrencyLimits method.
invalid_scheduler_policy_thread_specification Class	This class describes an exception that is thrown whenever an attempt is made to set the concurrency limits of a SchedulerPolicy object such that the value of the MinConcurrency key is less than the value of the MaxConcurrency key.
invalid_scheduler_policy_value Class	This class describes an exception that is thrown whenever a policy key of a SchedulerPolicy object is set to an invalid value for that key.
ISource Class	The ISource class is the interface for all source blocks. Source blocks propagate messages to ITarget blocks.
ITarget Class	The ITarget class is the interface for all target blocks. Target blocks consume messages offered to them by ISource blocks.
join Class	A join messaging block is a single-target, multi-source, ordered propagator_block which combines together messages of type _Type from each of its sources.
message Class	The basic message envelope containing the data payload being passed between messaging blocks.
message_not_found Class	This class describes an exception that is thrown whenever a messaging block is unable to find a requested message.
message_processor Class	The message_processor class is the abstract base class for processing of message objects. There is no guarantee on the ordering of the messages.
missing_wait Class	This class describes an exception that is thrown whenever there are tasks still scheduled to a task_group or structured_task_group object at the time that object's destructor executes. This exception will never be thrown if the destructor is reached due to stack unwinding as the result of an exception.
multi_link_registry Class	The multi_link_registry object is a network_link_registry that manages multiple source blocks or multiple target blocks.
multitype_join Class	A multitype_join messaging block is a multi-source, single-target messaging block that combines together messages of different types from each of its sources and offers a tuple of the combined messages to its targets.
nested_scheduler_missing_detach Class	This class describes an exception that is thrown when the Concurrency Runtime detects that you neglected to call the CurrentScheduler::Detach method on a context that attached to a second scheduler via the Attach method of the Scheduler object.
network_link_registry Class	The network_link_registry abstract base class manages the links between source and target blocks.
operation_timed_out Class	This class describes an exception that is thrown when an operation has timed out.
ordered_message_processor Class	An ordered_message_processor is a message_processor that allows message blocks to process messages in the order they were received.
overwrite_buffer Class	An overwrite_buffer messaging block is a multi-target, multi-source, ordered propagator_block capable of storing a single message at a time. New messages overwrite previously held ones.
propagator_block Class	The propagator_block class is an abstract base class for message blocks that are both a source and target. It combines the functionality of both the source_block and target_block classes.
reader_writer_lock Class	A writer-preference queue-based reader-writer lock with local only spinning. The lock grants first in - first out (FIFO) access to writers and starves readers under a continuous load of writers.
ScheduleGroup Class	Represents an abstraction for a schedule group. Schedule groups organize a set of related work that benefits from being scheduled close together either temporally, by executing another task in the same group before moving to another group, or spatially, by executing multiple items within the same group on the same NUMA node or physical socket.
Scheduler Class	Represents an abstraction for a Concurrency Runtime scheduler.
scheduler_not_attached Class	This class describes an exception that is thrown whenever an operation is performed which requires a scheduler to be attached to the current context and one is not.
scheduler_resource_allocation_error Class	This class describes an exception that is thrown due to failure to acquire a critical resource in the Concurrency Runtime.
SchedulerPolicy Class	The SchedulerPolicy class contains a set of key/value pairs, one for each policy element, that control the behavior of a scheduler instance.
single_assignment Class	A single_assignment messaging block is a multi-target, multi-source, ordered propagator_block capable of storing a single, write-once message.
single_link_registry Class	The single_link_registry object is a network_link_registry that manages only a single source or target block.
source_block Class	The source_block class is an abstract base class for source-only blocks. The class provides basic link management functionality as well as common error checks.
source_link_manager Class	The source_link_manager object manages messaging block network links to ISource blocks.
structured_task_group Class	The structured_task_group class represents a highly structured collection of parallel work. You can queue individual parallel tasks to a structured_task_group using task_handle objects, and wait for them to complete, or cancel the task group before they have finished executing, which will abort any tasks that have not begun execution.
target_block Class	The target_block class is an abstract base class that provides basic link management functionality and error checking for target only blocks.
task_group Class	The task_group class represents a collection of parallel work which can be waited on or canceled.
task_handle Class	The task_handle class represents an individual parallel work item. It encapsulates the instructions and the data required to execute a piece of work.
timer Class	A timer messaging block is a single-target source_block capable of sending a message to its target after a specified time period has elapsed or at specific intervals.
transformer Class	A transformer messaging block is a single-target, multi-source, ordered propagator_block which can accept messages of one type and is capable of storing an unbounded number of messages of a different type.
unbounded_buffer Class	An unbounded_buffer messaging block is a multi-target, multi-source, ordered propagator_block capable of storing an unbounded number of messages.
unsupported_os Class	This class describes an exception that is thrown whenever an unsupported operating system is used. The Concurrency Runtime does not support operating systems earlier than Windows XP with Service Pack 3.

Structures

Name	Description
DispatchState Structure	The DispatchState structure is used to transfer state to the IExecutionContext::Dispatch method. It describes the circumstances under which the Dispatch method is invoked on an IExecutionContext interface.
IExecutionContext Structure	An interface to an execution context which can run on a given virtual processor and be cooperatively context switched.
IExecutionResource Structure	An abstraction for a hardware thread.
IResourceManager Structure	An interface to the Concurrency Runtime's Resource Manager. This is the interface by which schedulers communicate with the Resource Manager.
IScheduler Structure	An interface to an abstraction of a work scheduler. The Concurrency Runtime's Resource Manager uses this interface to communicate with work schedulers.
ISchedulerProxy Structure	The interface by which schedulers communicate with the Concurrency Runtime's Resource Manager to negotiate resource allocation.
IThreadProxy Structure	An abstraction for a thread of execution. Depending on the SchedulerType policy key of the scheduler you create, the Resource Manager will grant you a thread proxy that is backed by either a regular Win32 thread or a user-mode schedulable (UMS) thread. UMS threads are supported on 64-bit operating systems with version Windows 7 and higher.
IUMSCompletionList Structure	Represents a UMS completion list. When a UMS thread blocks, the scheduler's designated scheduling context is dispatched in order to make a decision of what to schedule on the underlying virtual processor root while the original thread is blocked. When the original thread unblocks, the operating system queues it to the completion list which is accessible through this interface. The scheduler can query the completion list on the designated scheduling context or any other place it searches for work.
IUMSScheduler Structure	An interface to an abstraction of a work scheduler that wants the Concurrency Runtime's Resource Manager to hand it user-mode schedulable (UMS) threads. The Resource Manager uses this interface to communicate with UMS thread schedulers. The IUMSScheduler interface inherits from the IScheduler interface.
IUMSThreadProxy Structure	An abstraction for a thread of execution. If you want your scheduler to be granted user-mode schedulable (UMS) threads, set the value for the scheduler policy element SchedulerKind to UmsThreadDefault, and implement the IUMSScheduler interface. UMS threads are only supported on 64-bit operating systems with version Windows 7 and higher.
IUMSUnblockNotification Structure	Represents a notification from the Resource Manager that a thread proxy which blocked and triggered a return to the scheduler's designated scheduling context has unblocked and is ready to be scheduled. This interface is invalid once the thread proxy's associated execution context, returned from the GetContext method, is rescheduled.
IVirtualProcessorRoot Structure	An abstraction for a hardware thread on which a thread proxy can execute.

Enumerations

Name	Description
agent_status Enumeration	The valid states for an agent.
ConcRT_EventType Enumeration	The types of events that can be traced using the tracing functionality offered by the Concurrency Runtime.
CriticalRegionType Enumeration	The type of critical region a context is inside.
DynamicProgressFeedbackType Enumeration	Used by the DynamicProgressFeedback policy to describe whether resources for the scheduler will be rebalanced according to statistical information gathered from the scheduler or only based on virtual processors going in and out of the idle state through calls to the Activate and Deactivate methods on the IVirtualProcessorRoot interface. For more information on available scheduler policies, see PolicyElementKey Enumeration.
join_type Enumeration	The type of a join messaging block.
message_status Enumeration	The valid responses for an offer of a message object to a block.
PolicyElementKey Enumeration	Policy keys describing aspects of scheduler behavior. Each policy element is described by a key-value pair. For more information about scheduler policies and their impact on schedulers, see Task Scheduler (Concurrency Runtime).
SchedulerType Enumeration	Used by the SchedulerKind policy to describe the type of threads that the scheduler should utilize for underlying execution contexts. For more information on available scheduler policies, see PolicyElementKey Enumeration.
SchedulingProtocolType Enumeration	Used by the SchedulingProtocol policy to describe which scheduling algorithm will be utilized for the scheduler. For more information on available scheduler policies, see PolicyElementKey Enumeration.
SwitchingProxyState Enumeration	Used to denote the state a thread proxy is in, when it is executing a cooperative context switch to a different thread proxy.
task_group_status Enumeration	Describes the execution status of a task_group or structured_task_group object. A value of this type is returned by numerous methods that wait on tasks scheduled to a task group to complete.

Functions

Name	Description
asend Function	Overloaded. An asynchronous send operation, which schedules a task to propagate the data to the target block.
make_choice Function	Overloaded. Constructs a choice messaging block from an optional Scheduler or ScheduleGroup and between two and ten input sources.
make_greedy_join Function	Overloaded. Constructs a greedy multitype_join messaging block from an optional Scheduler or ScheduleGroup and between two and ten input sources.
make_join Function	Overloaded. Constructs a non_greedy multitype_join messaging block from an optional Scheduler or ScheduleGroup and between two and ten input sources.
make_task Function	A factory method for creating a task_handle object.
parallel_for Function	Overloaded. parallel_for iterates over a range of indices and executes a user-supplied function at each iteration, in parallel.
parallel_for_each Function	parallel_for_each applies a specified function to each element within a range, in parallel. It is semantically equivalent to the for_each function in the std namespace, except that iteration over the elements is performed in parallel, and the order of iteration is unspecified. The argument _Func must support a function call operator of the form operator()(T) where the parameter T is the item type of the container being iterated over.
parallel_invoke Function	Overloaded. Executes the function objects supplied as parameters in parallel, and blocks until they have finished executing. Each function object could be a lambda expression, a pointer to function, or any object that supports the function call operator with the signature void operator()().
receive Function	Overloaded. A general receive implementation, allowing a context to wait for data from exactly one source and filter the values that are accepted.
send Function	Overloaded. A synchronous send operation, which waits until the target either accepts or declines the message.
swap Function	Exchanges the elements of two concurrent_vector objects.
try_receive Function	Overloaded. A general try-receive implementation, allowing a context to look for data from exactly one source and filter the values that are accepted. If the data is not ready, the method will return false.

Operators

Name	Description
operator!= Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is not equal to the concurrent_vector object on the right side.
operator< Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is less than the concurrent_vector object on the right side.
operator<= Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is less than or equal to the concurrent_vector object on the right side.
operator== Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is equal to the concurrent_vector object on the right side.
operator> Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is greater than the concurrent_vector object on the right side.
operator>= Operator (concurrent_vector)	Tests if the concurrent_vector object on the left side of the operator is greater than or equal to the concurrent_vector object on the right side.

Constants

Name	Description
ChoreEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to chores or tasks.
ConcRT_ProviderGuid Constant	The ETW provider GUID for the Concurrency Runtime.
CONCRT_RM_VERSION_1 Constant	Indicates support of the Resource Manager interface defined in Visual Studio 2010.
ConcRTEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are not more specifically described by another category.
ContextEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to contexts.
COOPERATIVE_TIMEOUT_INFINITE Constant	Value indicating that a wait should never time out.
COOPERATIVE_WAIT_TIMEOUT Constant	Value indicating that a wait timed out.
INHERIT_THREAD_PRIORITY Constant	Special value for the policy key ContextPriority indicating that the thread priority of all contexts in the scheduler should be the same as that of the thread which created the scheduler.
LockEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to locks.
MaxExecutionResources Constant	Special value for the policy keys MinConcurrency and MaxConcurrency. Defaults to the number of hardware threads on the machine in the absence of other constraints.
PPLParallelForeachEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to usage of the parallel_for_each function.
PPLParallelForEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to usage of the parallel_for function.
PPLParallelInvokeEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to usage of the parallel_invoke function.
ResourceManagerEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to the resource manager.
ScheduleGroupEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to schedule groups.
SchedulerEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to scheduler activity.
VirtualProcessorEventGuid Constant	A category GUID describing ETW events fired by the Concurrency Runtime that are directly related to virtual processors.

Requirements

Header: agents.h, concrt.h, concrtrm.h, concurrent_queue.h, concurrent_vector.h, ppl.h