task_continuation_context Class
The task_continuation_context class allows you to specify where you would like a continuation to be executed. It is only useful to use this class from a Windows Runtime app. For non-Windows Runtime apps, the task continuation's execution context is determined by the runtime, and not configurable.
Syntax
class task_continuation_context : public details::_ContextCallback;
Members
Public Methods
| Name | Description |
|---|---|
| get_current_winrt_context | Returns a task continuation context object that represents the current winrt thread context. |
| use_arbitrary | Creates a task continuation context which allows the Runtime to choose the execution context for a continuation. |
| use_current | Returns a task continuation context object that represents the current execution context. |
| use_default | Creates the default task continuation context. |
| use_synchronous_execution | Returns a task continuation context object that represents the synchronous execution context. |
Inheritance Hierarchy
_ContextCallback
task_continuation_context
Requirements
Header: ppltasks.h
Namespace: concurrency
get_current_winrt_context
Returns a task continuation context object that represents the current WinRT thread context.
Syntax
static task_continuation_context get_current_winrt_context();
Return Value
The current Windows Runtime thread context. Returns an empty task_continuation_context if called from a non-Windows Runtime context.
Remarks
The get_current_winrt_context method captures the caller's Windows Runtime thread context. It returns an empty context to non-Windows Runtime callers.
The value returned by get_current_winrt_context can be used to indicate to the Runtime that the continuation should execute in the apartment model of the captured context (STA vs MTA), regardless of whether the antecedent task is apartment aware. An apartment aware task is a task that unwraps a Windows Runtime IAsyncInfo interface, or a task that is descended from such a task.
This method is similar to the use_current method, but it is also available to native C++ code without C++/CX extension support. It is intended for use by advanced users writing C++/CX-agnostic library code for both native and Windows Runtime callers. Unless you need this functionality, we recommend the use_current method, which is only available to C++/CX clients.
use_arbitrary
Creates a task continuation context which allows the Runtime to choose the execution context for a continuation.
Syntax
static task_continuation_context use_arbitrary();
Return Value
A task continuation context that represents an arbitrary location.
Remarks
When this continuation context is used the continuation will execute in a context the runtime chooses even if the antecedent task is apartment aware.
use_arbitrary can be used to turn off the default behavior for a continuation on an apartment aware task created in an STA.
This method is only available to Windows Runtime apps.
use_current
Returns a task continuation context object that represents the current execution context.
static task_continuation_context use_current();
Return Value
The current execution context.
Remarks
This method captures the caller's Windows Runtime context so that continuations can be executed in the right apartment.
The value returned by use_current can be used to indicate to the Runtime that the continuation should execute in the captured context (STA vs MTA) regardless of whether or not the antecedent task is apartment aware. An apartment aware task is a task that unwraps a Windows Runtime IAsyncInfo interface, or a task that is descended from such a task.
This method is only available to Windows Runtime apps.
use_default
Creates the default task continuation context.
static task_continuation_context use_default();
Return Value
The default continuation context.
Remarks
The default context is used if you don't specify a continuation context when you call the then method. In Windows applications for Windows 7 and below, as well as desktop applications on Windows 8 and higher, the runtime determines where task continuations will execute. However, in a Windows Runtime app, the default continuation context for a continuation on an apartment aware task is the apartment where then is invoked.
An apartment aware task is a task that unwraps a Windows Runtime IAsyncInfo interface, or a task that is descended from such a task. Therefore, if you schedule a continuation on an apartment aware task in a Windows Runtime STA, the continuation will execute in that STA.
A continuation on a non-apartment aware task will execute in a context the Runtime chooses.
task_continuation_context::use_synchronous_execution
Returns a task continuation context object that represents the synchronous execution context.
Syntax
static task_continuation_context use_synchronous_execution();
Return Value
The synchronous execution context.
Remarks
The use_synchronous_execution method forces the continuation task to run synchronously on the context, causing its antecedent task's completion.
If the antecedent task has already completed when the continuation is attached, the continuation runs synchronously on the context that attaches the continuation.