Context Class
Represents an abstraction for an execution context.
Syntax
class Context;
Members
Protected Constructors
| Name | Description |
|---|---|
| ~Context Destructor |
Public Methods
| Name | Description |
|---|---|
| Block | Blocks the current context. |
| CurrentContext | Returns a pointer to the current context. |
| GetId | Returns an identifier for the context that is unique within the scheduler to which the context belongs. |
| GetScheduleGroupId | Returns an identifier for the schedule group that the context is currently working on. |
| GetVirtualProcessorId | Returns an identifier for the virtual processor that the context is currently executing on. |
| Id | Returns an identifier for the current context that is unique within the scheduler to which the current context belongs. |
| IsCurrentTaskCollectionCanceling | Returns an indication of whether the task collection which is currently executing inline on the current context is in the midst of an active cancellation (or will be shortly). |
| IsSynchronouslyBlocked | Determines whether or not the context is synchronously blocked. A context is considered to be synchronously blocked if it explicitly performed an action which led to blocking. |
| Oversubscribe | Injects an additional virtual processor into a scheduler for the duration of a block of code when invoked on a context executing on one of the virtual processors in that scheduler. |
| ScheduleGroupId | Returns an identifier for the schedule group that the current context is working on. |
| Unblock | Unblocks the context and causes it to become runnable. |
| VirtualProcessorId | Returns an identifier for the virtual processor that the current context is executing on. |
| Yield | Yields execution so that another context can execute. If no other context is available to yield to, the scheduler can yield to another operating system thread. |
Remarks
The Concurrency Runtime scheduler (see Scheduler) uses execution contexts to execute the work queued to it by your application. A Win32 thread is an example of an execution context on a Windows operating system.
At any time, the concurrency level of a scheduler is equal to the number of virtual processors granted to it by the Resource Manager. A virtual processor is an abstraction for a processing resource and maps to a hardware thread on the underlying system. Only a single scheduler context can execute on a virtual processor at a given time.
The scheduler is cooperative in nature and an executing context can yield its virtual processor to a different context at any time if it wishes to enter a wait state. When its wait it satisfied, it cannot resume until an available virtual processor from the scheduler begins executing it.
Inheritance Hierarchy
Context
Requirements
Header: concrt.h
Namespace: concurrency
Block
Blocks the current context.
static void __cdecl Block();
Remarks
This method will result in the process' default scheduler being created and/or attached to the calling context if there is no scheduler currently associated with the calling context.
If the calling context is running on a virtual processor, the virtual processor will find another runnable context to execute or can potentially create a new one.
After the Block method has been called or will be called, you must pair it with a call to the Unblock method from another execution context in order for it to run again. Be aware that there is a critical period between the point where your code publishes its context for another thread to be able to call the Unblock method and the point where the actual method call to Block is made. During this period, you must not call any method which can in turn block and unblock for its own reasons (for example, acquiring a lock). Calls to the Block and Unblock method do not track the reason for the blocking and unblocking. Only one object should have ownership of a Block- Unblock pair.
This method can throw a variety of exceptions, including scheduler_resource_allocation_error.
~Context
virtual ~Context();
CurrentContext
Returns a pointer to the current context.
static Context* __cdecl CurrentContext();
Return Value
A pointer to the current context.
Remarks
This method will result in the process' default scheduler being created and/or attached to the calling context if there is no scheduler currently associated with the calling context.
GetId
Returns an identifier for the context that is unique within the scheduler to which the context belongs.
virtual unsigned int GetId() const = 0;
Return Value
An identifier for the context that is unique within the scheduler to which the context belongs.
GetScheduleGroupId
Returns an identifier for the schedule group that the context is currently working on.
virtual unsigned int GetScheduleGroupId() const = 0;
Return Value
An identifier for the schedule group the context is currently working on.
Remarks
The return value from this method is an instantaneous sampling of the schedule group that the context is executing on. If this method is called on a context other than the current context, the value can be stale the moment it is returned and cannot be relied upon. Typically, this method is used for debugging or tracing purposes only.
GetVirtualProcessorId
Returns an identifier for the virtual processor that the context is currently executing on.
virtual unsigned int GetVirtualProcessorId() const = 0;
Return Value
If the context is currently executing on a virtual processor, an identifier for the virtual processor that the context is currently executing on; otherwise, the value -1.
Remarks
The return value from this method is an instantaneous sampling of the virtual processor that the context is executing on. This value can be stale the moment it is returned and cannot be relied upon. Typically, this method is used for debugging or tracing purposes only.
Id
Returns an identifier for the current context that is unique within the scheduler to which the current context belongs.
static unsigned int __cdecl Id();
Return Value
If the current context is attached to a scheduler, an identifier for the current context that is unique within the scheduler to which the current context belongs; otherwise, the value -1.
IsCurrentTaskCollectionCanceling
Returns an indication of whether the task collection which is currently executing inline on the current context is in the midst of an active cancellation (or will be shortly).
static bool __cdecl IsCurrentTaskCollectionCanceling();
Return Value
If a scheduler is attached to the calling context and a task group is executing a task inline on that context, an indication of whether that task group is in the midst of an active cancellation (or will be shortly); otherwise, the value false.
IsSynchronouslyBlocked
Determines whether or not the context is synchronously blocked. A context is considered to be synchronously blocked if it explicitly performed an action which led to blocking.
virtual bool IsSynchronouslyBlocked() const = 0;
Return Value
Whether the context is synchronously blocked.
Remarks
A context is considered to be synchronously blocked if it explicitly performed an action which led to blocking. On the thread scheduler, this would indicate a direct call to the Context::Block method or a synchronization object which was built using the Context::Block method.
The return value from this method is an instantaneous sample of whether the context is synchronously blocked. This value may be stale the moment it is returned and can only be used under very specific circumstances.
operator delete
A Context object is destroyed internally by the runtime. It can not be explicitly deleted.
void operator delete(void* _PObject);
Parameters
_PObject
A pointer to the object to be deleted.
Oversubscribe
Injects an additional virtual processor into a scheduler for the duration of a block of code when invoked on a context executing on one of the virtual processors in that scheduler.
static void __cdecl Oversubscribe(bool _BeginOversubscription);
Parameters
_BeginOversubscription
If true, an indication that an extra virtual processor should be added for the duration of the oversubscription. If false, an indication that the oversubscription should end and the previously added virtual processor should be removed.
ScheduleGroupId
Returns an identifier for the schedule group that the current context is working on.
static unsigned int __cdecl ScheduleGroupId();
Return Value
If the current context is attached to a scheduler and working on a schedule group, an identifier for the scheduler group that the current context is working on; otherwise, the value -1.
Unblock
Unblocks the context and causes it to become runnable.
virtual void Unblock() = 0;
Remarks
It is perfectly legal for a call to the Unblock method to come before a corresponding call to the Block method. As long as calls to the Block and Unblock methods are properly paired, the runtime properly handles the natural race of either ordering. An Unblock call coming before a Block call simply negates the effect of the Block call.
There are several exceptions which can be thrown from this method. If a context attempts to call the Unblock method on itself, a context_self_unblock exception will be thrown. If calls to Block and Unblock are not properly paired (for example, two calls to Unblock are made for a context which is currently running), a context_unblock_unbalanced exception will be thrown.
Be aware that there is a critical period between the point where your code publishes its context for another thread to be able to call the Unblock method and the point where the actual method call to Block is made. During this period, you must not call any method which can in turn block and unblock for its own reasons (for example, acquiring a lock). Calls to the Block and Unblock method do not track the reason for the blocking and unblocking. Only one object should have ownership of a Block and Unblock pair.
VirtualProcessorId
Returns an identifier for the virtual processor that the current context is executing on.
static unsigned int __cdecl VirtualProcessorId();
Return Value
If the current context is attached to a scheduler, an identifier for the virtual processor that the current context is executing on; otherwise, the value -1.
Remarks
The return value from this method is an instantaneous sampling of the virtual processor that the current context is executing on. This value can be stale the moment it is returned and cannot be relied upon. Typically, this method is used for debugging or tracing purposes only.
Yield
Yields execution so that another context can execute. If no other context is available to yield to, the scheduler can yield to another operating system thread.
static void __cdecl Yield();
Remarks
This method will result in the process' default scheduler being created and/or attached to the calling context if there is no scheduler currently associated with the calling context.
YieldExecution
Yields execution so that another context can execute. If no other context is available to yield to, the scheduler can yield to another operating system thread.
static void __cdecl YieldExecution();
Remarks
This method will result in the process' default scheduler being created and/or attached to the calling context if there is no scheduler currently associated with the calling context.
This function is new in Visual Studio 2015 and is identical to the Yield function but does not conflict with the Yield macro in Windows.h.