Parameters

Creates a Windows Runtime asynchronous construct based on a user supplied lambda or function object. The return type of create_async is one of either IAsyncAction^, IAsyncActionWithProgress<TProgress>^, IAsyncOperation<TResult>^, or IAsyncOperationWithProgress<TResult, TProgress>^ based on the signature of the lambda passed to the method.

Parameters

_Function_Func
The lambda or function object from which to create a Windows Runtime asynchronous construct.

Return Value

An asynchronous construct represented by an IAsyncAction^, IAsyncActionWithProgress<TProgress>^, IAsyncOperation<TResult>^, or an IAsyncOperationWithProgress<TResult, TProgress>^. The interface returned depends on the signature of the lambda passed into the function.

Remarks

The return type of the lambda determines whether the construct is an action or an operation.

Lambdas that return void cause the creation of actions. Lambdas that return a result of type TResult cause the creation of operations of TResult.

The lambda may also return a task<TResult> which encapsulates the aysnchronous work within itself or is the continuation of a chain of tasks that represent the asynchronous work. In this case, the lambda itself is executed inline, since the tasks are the ones that execute asynchronously, and the return type of the lambda is unwrapped to produce the asynchronous construct returned by create_async. This implies that a lambda that returns a task<void> will cause the creation of actions, and a lambda that returns a task<TResult> will cause the creation of operations of TResult.

The lambda may take either zero, one or two arguments. The valid arguments are progress_reporter<TProgress> and cancellation_token, in that order if both are used. A lambda without arguments causes the creation of an asynchronous construct without the capability for progress reporting. A lambda that takes a progress_reporter<TProgress> will cause create_async to return an asynchronous construct which reports progress of type TProgress each time the report method of the progress_reporter object is called. A lambda that takes a cancellation_token may use that token to check for cancellation, or pass it to tasks that it creates so that cancellation of the asynchronous construct causes cancellation of those tasks.

If the body of the lambda or function object returns a result (and not a task<TResult>), the lamdba will be executed asynchronously within the process MTA in the context of a task the Runtime implicitly creates for it. The IAsyncInfo::Cancel method will cause cancellation of the implicit task.

If the body of the lambda returns a task, the lamba executes inline, and by declaring the lambda to take an argument of type cancellation_token you can trigger cancellation of any tasks you create within the lambda by passing that token in when you create them. You may also use the register_callback method on the token to cause the Runtime to invoke a callback when you call IAsyncInfo::Cancel on the async operation or action produced..

Returns an interface that represents the singleton instance of the Concurrency Runtime's Resource Manager. The Resource Manager is responsible for assigning resources to schedulers that want to cooperate with each other.

Return Value

An IResourceManager interface.

Remarks

Multiple subsequent calls to this method will return the same instance of the Resource Manager. Each call to the method increments a reference count on the Resource Manager, and must be matched with a call to the IResourceManager::Release method when your scheduler is done communicating with the Resource Manager.

unsupported_os is thrown if the operating system is not supported by the Concurrency Runtime.

Creates a PPL task object. create_task can be used anywhere you would have used a task constructor. It is provided mainly for convenience, because it allows use of the auto keyword while creating tasks.

Parameters

T
The type of the parameter from which the task is to be constructed.

_ReturnType_Param
The parameter from which the task is to be constructed. This could be a lambda or function object, a task_completion_event object, a different task object, or a Windows::Foundation::IAsyncInfo interface if you are using tasks in your Windows Store app.

_TaskOptions_Task

Return Value

A new task of type T, that is inferred from _Param.

Remarks

The first overload behaves like a task constructor that takes a single parameter.

The second overload associates the cancellation token provided with the newly created task. If you use this overload you are not allowed to pass in a different task object as the first parameter.

The type of the returned task is inferred from the first parameter to the function. If _Param is a task_completion_event<T>, a task<T>, or a functor that returns either type T or task<T>, the type of the created task is task<T>.

In a Windows Store app, if _Param is of type Windows::Foundation::IAsyncOperation<T>^ or Windows::Foundation::IAsyncOperationWithProgress<T,P>^, or a functor that returns either of those types, the created task will be of type task<T>. If _Param is of type Windows::Foundation::IAsyncAction^ or Windows::Foundation::IAsyncActionWithProgress<P>^, or a functor that returns either of those types, the created task will have type task<void>.

Parameters

_PAllocation
A pointer to memory previously allocated by the Alloc method which is to be freed. If the parameter _PAllocation is set to the value NULL, this method will ignore it and return immediately.

Remarks

For more information about which scenarios in your application could benefit from using the Caching Suballocator, see Task Scheduler.

Parameters

Creates an interruption point for cancellation. If a cancellation is in progress in the context where this function is called, this will throw an internal exception that aborts the execution of the currently executing parallel work. If cancellation is not in progress, the function does nothing.

Remarks

You should not catch the internal cancellation exception thrown by the interruption_point() function. The exception will be caught and handled by the runtime, and catching it may cause your program to behave abnormally.

Returns an indication of whether the task group which is currently executing inline on the current context is in the midst of an active cancellation (or will be shortly). Note that if there is no task group currently executing inline on the current context, false will be returned.

Parameters

_Function
The type of the function object that will be invoked to execute the work represented by the task_handle object.

_Func
The function that will be invoked to execute the work represented by the task_handle object. This may be a lambda functor, a pointer to a function, or any object that supports a version of the function call operator with the signature void operator()().

Return Value

A task_handle object.

Remarks

This function is useful when you need to create a task_handle object with a lambda expression, because it allows you to create the object without knowing the true type of the lambda functor.

Arranges the elements in a specified range into a nondescending order, or according to an ordering criterion specified by a binary predicate, in parallel. This function is semantically similar to std::sort in that it is a compare-based, unstable, in-place sort except that it needs O(n) additional space, and requires default initialization for the elements being sorted.

Parameters

_Begin
A random-access iterator addressing the position of the first element in the range to be sorted.

_End
A random-access iterator addressing the position one past the final element in the range to be sorted.

_Alloc
An instance of an STL compatible memory allocator.

_Func
A user-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns true when satisfied and false when not satisfied. This comparator function must impose a strict weak ordering on pairs of elements from the sequence.

_Chunk_size
The mimimum size of a chunk that will be split into two for parallel execution.

Remarks

All overloads require n * sizeof(T) additional space, where n is the number of elements to be sorted, and T is the element type. In most cases parallel_buffered_sort will show an improvement in performance over parallel_sort, and you should use it over parallel_sort if you have the memory available.

If you do not supply a binary comparator std::less is used as the default, which requires the element type to provide the operator operator<().

If you do not supply an allocator type or instance, the STL memory allocator std::allocator<T> is used to allocate the buffer.

The algorithm divides the input range into two chunks and successively divides each chunk into two sub-chunks for execution in parallel. The optional argument _Chunk_size can be used to indicate to the algorithm that it should handles chunks of size < _Chunk_size serially.

Parameters

_Function
The type of the function that will be executed at each iteration.

_Partitioner
The type of the partitioner that is used to partition the supplied range.

first
The first index to be included in the iteration.

last
The index one past the last index to be included in the iteration.

_Step
The value by which to step when iterating from first to last. The step must be positive. invalid_argument is thrown if the step is less than 1.

_Func
The function to be executed at each iteration. This may be a lambda expression, a function pointer, or any object that supports a version of the function call operator with the signature void operator()(``_Index_type``).

Remarks

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.

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()().

Parameters

_Function1
The type of the first function object to be executed in parallel.

_Function2
The type of the second function object to be executed in parallel.

_Function3
The type of the third function object to be executed in parallel.

_Function4
The type of the fourth function object to be executed in parallel.

_Function5
The type of the fifth function object to be executed in parallel.

_Function6
The type of the sixth function object to be executed in parallel.

_Function7
The type of the seventh function object to be executed in parallel.

_Function8
The type of the eighth function object to be executed in parallel.

_Function9
The type of the ninth function object to be executed in parallel.

_Function10
The type of the tenth function object to be executed in parallel.

_Func1
The first function object to be executed in parallel.

_Func2
The second function object to be executed in parallel.

_Func3
The third function object to be executed in parallel.

_Func4
The fourth function object to be executed in parallel.

_Func5
The fifth function object to be executed in parallel.

_Func6
The sixth function object to be executed in parallel.

_Func7
The seventh function object to be executed in parallel.

_Func8
The eighth function object to be executed in parallel.

_Func9
The ninth function object to be executed in parallel.

_Func10
The tenth function object to be executed in parallel.

Remarks

Note that one or more of the function objects supplied as parameters may execute inline on the calling context.

If one or more of the function objects passed as parameters to this function throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to parallel_invoke.

Arranges elements in a specified range into an non descending order using a radix sorting algorithm. This is a stable sort function which requires a projection function that can project elements to be sorted into unsigned integer-like keys. Default initialization is required for the elements being sorted.

Parameters

_Begin
A random-access iterator addressing the position of the first element in the range to be sorted.

_End
A random-access iterator addressing the position one past the final element in the range to be sorted.

_Alloc
An instance of an STL compatible memory allocator.

_Proj_func
A user-defined projection function object that converts an element into an integral value.

_Chunk_size
The mimimum size of a chunk that will be split into two for parallel execution.

Remarks

All overloads require n * sizeof(T) additional space, where n is the number of elements to be sorted, and T is the element type. An unary projection functor with the signature I _Proj_func(T) is required to return a key when given an element, where T is the element type and I is an unsigned integer-like type.

If you do not supply a projection function, a default projection function which simply returns the element is used for integral types. The function will fail to compile if the element is not an integral type in the absence of a projection function.

If you do not supply an allocator type or instance, the STL memory allocator std::allocator<T> is used to allocate the buffer.

The algorithm divides the input range into two chunks and successively divides each chunk into two sub-chunks for execution in parallel. The optional argument _Chunk_size can be used to indicate to the algorithm that it should handles chunks of size < _Chunk_size serially.

Computes the sum of all elements in a specified range by computing successive partial sums, or computes the result of successive partial results similarly obtained from using a specified binary operation other than sum, in parallel. parallel_reduce is semantically similar to std::accumulate, except that it requires the binary operation to be associative, and requires an identity value instead of an initial value.

Parameters

_Forward_iterator
The iterator type of input range.

_Sym_reduce_fun
The type of the symmetric reduction function. This must be a function type with signature _Reduce_type _Sym_fun(_Reduce_type, _Reduce_type), where _Reduce_type is the same as the identity type and the result type of the reduction. For the third overload, this should be consistent with the output type of _Range_reduce_fun.

_Reduce_type
The type that the input will reduce to, which can be different from the input element type. The return value and identity value will has this type.

_Range_reduce_fun
The type of the range reduction function. This must be a function type with signature _Reduce_type _Range_fun(_Forward_iterator, _Forward_iterator, _Reduce_type), _Reduce_type is the same as the identity type and the result type of the reduction.

_Begin
An input iterator addressing the first element in the range to be reduced.

_End
An input iterator addressing the element that is one position beyond the final element in the range to be reduced.

_Identity
The identity value _Identity is of the same type as the result type of the reduction and also the value_type of the iterator for the first and second overloads. For the third overload, the identity value must have the same type as the result type of the reduction, but can be different from the value_type of the iterator. It must have an appropriate value such that the range reduction operator _Range_fun, when applied to a range of a single element of type value_type and the identity value, behaves like a type cast of the value from type value_type to the identity type.

_Sym_fun
The symmetric function that will be used in the second of the reduction. Refer to Remarks for more information.

_Range_fun
The function that will be used in the first phase of the reduction. Refer to Remarks for more information.

Return Value

The result of the reduction.

Remarks

To perform a parallel reduction, the function divides the range into chunks based on the number of workers available to the underlying scheduler. The reduction takes place in two phases, the first phase performs a reduction within each chunk, and the second phase performs a reduction between the partial results from each chunk.

The first overload requires that the iterator's value_type, T, be the same as the identity value type as well as the reduction result type. The element type T must provide the operator T T::operator + (T) to reduce elements in each chunk. The same operator is used in the second phase as well.

The second overload also requires that the iterator's value_type be the same as the identity value type as well as the reduction result type. The supplied binary operator _Sym_fun is used in both reduction phases, with the identity value as the initial value for the first phase.

For the third overload, the identity value type must be the same as the reduction result type, but the iterator's value_type may be different from both. The range reduction function _Range_fun is used in the first phase with the identity value as the initial value, and the binary function _Sym_reduce_fun is applied to sub results in the second phase.

Arranges the elements in a specified range into a nondescending order, or according to an ordering criterion specified by a binary predicate, in parallel. This function is semantically similar to std::sort in that it is a compare-based, unstable, in-place sort.

Parameters

_Begin
A random-access iterator addressing the position of the first element in the range to be sorted.

_End
A random-access iterator addressing the position one past the final element in the range to be sorted.

_Func
A user-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns true when satisfied and false when not satisfied. This comparator function must impose a strict weak ordering on pairs of elements from the sequence.

_Chunk_size
The mimimum size of a chunk that will be split into two for parallel execution.

Remarks

The first overload uses the the binary comparator std::less.

The second overloaded uses the supplied binary comparator that should have the signature bool _Func(T, T) where T is the type of the elements in the input range.

The algorithm divides the input range into two chunks and successively divides each chunk into two sub-chunks for execution in parallel. The optional argument _Chunk_size can be used to indicate to the algorithm that it should handles chunks of size < _Chunk_size serially.

Applies a specified function object to each element in a source range, or to a pair of elements from two source ranges, and copies the return values of the function object into a destination range, in parallel. This functional is semantically equivalent to std::transform.

first2
An input iterator addressing the position of the first element in the second source range to be operated on.

_Binary_op
A user-defined binary function object that is applied pairwise, in a forward order, to the two source ranges.

Return Value

An output iterator addressing the position one past the final element in the destination range that is receiving the output elements transformed by the function object.

Remarks

auto_partitioner will be used for the overloads without an explicit partitioner argument.

For iterators that do not support random access, only auto_partitioner is supported.

The overloads that take the argument _Unary_op transform the input range into the output range by applying the unary functor to each element in the input range. _Unary_op must support the function call operator with signature operator()(T) where T is the value type of the range being iterated over.

The overloads that take the argument _Binary_op transform two input ranges into the output range by applying the binary functor to one element from the first input range and one element from the second input range. _Binary_op must support the function call operator with signature operator()(T, U) where T, U are value types of the two input iterators.

Parameters

_Src
A pointer or reference to the source from which data is expected.

_Timeout
The maximum time for which the method should for the data, in milliseconds.

_Filter_proc
A filter function which determines whether messages should be accepted.

Return Value

A value from the source, of the payload type.

Remarks

If the parameter _Timeout has a value other than the constant COOPERATIVE_TIMEOUT_INFINITE, the exception operation_timed_out is thrown if the specified amount of time expires before a message is received. If you want a zero length timeout, you should use the try_receive function, as opposed to calling receive with a timeout of 0 (zero), as it is more efficient and does not throw exceptions on timeouts.

Parameters

_Function
The type of the function object that will be invoked.

_Func
The function object which will be executed. This object must support the function call operator with a signature of void(void).

_Ct
The cancellation token which will control implicit cancellation of the function object. Use cancellation_token::none() if you want the function execute without any possibility of implicit cancellation from a parent task group being canceled.

Remarks

Any interruption points in the function object will be triggered when the cancellation_token is canceled. The explicit token _Ct will isolate this _Func from parent cancellation if the parent has a different token or no token.

Parameters

Restricts the execution resources used by the Concurrency Runtime internal worker threads to the affinity set specified.

It is valid to call this method only before the Resource Manager has been created, or between two Resource Manager lifetimes. It can be invoked multiple times as long as the Resource Manager does not exist at the time of invocation. After an affinity limit has been set, it remains in effect until the next valid call to the set_task_execution_resources method.

The affinity mask provided need not be a subset of the process affinity mask. The process affinity will be updated if necessary.

Parameters

_ProcessAffinityMask
The affinity mask that the Concurrency Runtime worker threads are to be restricted to. Use this method on a system with greater than 64 hardware threads only if you want to limit the Concurrency Runtime to a subset of the current processor group. In general, you should use the version of the method that accepts an array of group affinities as a parameter, to restrict affinity on machines with greater than 64 hardware threads.

count
The number of GROUP_AFFINITY entries in the array specified by the parameter _PGroupAffinity.

_PGroupAffinity
An array of GROUP_AFFINITY entries.

Remarks

The method will throw an invalid_operation exception if a Resource Manager is present at the time it is invoked, and an invalid_argument exception if the affinity specified results in an empty set of resources.

The version of the method that takes an array of group affinities as a parameter should only be used on operating systems with version Windows 7 or higher. Otherwise, an invalid_operation exception is thrown.

Programatically modifying the process affinity after this method has been invoked will not cause the Resource Manager to re-evaluate the affinity it is restricted to. Therefore, all changes to process affinity should be made before calling this method.

Parameters

_A
The concurrent vector whose elements are to be exchanged with those of the concurrent vector _B.

_B
The concurrent vector providing the elements to be swapped, or the vector whose elements are to be exchanged with those of the concurrent vector _A.

Remarks

The template function is an algorithm specialized on the container class concurrent_vector to execute the member function _A. concurrent_vector::swap( _B). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, template <class T> void swap(T&, T&), in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class.

This method is not concurrency-safe. You must ensure that no other threads are performing operations on either of the concurrent vectors when you call this method.

Remarks

Parameters

_Milliseconds
The number of milliseconds the current context should be paused for. If the _Milliseconds parameter is set to the value 0, the current context should yield execution to other runnable contexts before continuing.

Remarks

If this method is called on a Concurrency Runtime scheduler context, the scheduler will find a different context to run on the underlying resource. Because the scheduler is cooperative in nature, this context cannot resume exactly after the number of milliseconds specified. If the scheduler is busy executing other tasks that do not cooperatively yield to the scheduler, the wait period could be indefinite.

Parameters

_Begin
The position of the first element in the range of elements to be combined into the resulting task.

_End
The position of the first element beyond the range of elements to be combined into the resulting task.

_TaskOptions

Return Value

A task that completes sucessfully when all of the input tasks have completed successfully. If the input tasks are of type T, the output of this function will be a task<std::vector<T>>. If the input tasks are of type void the output task will also be a task<void>.

Remarks

when_all is a non-blocking function that produces a task as its result. Unlike task::wait, it is safe to call this function in a Windows 8.x Store app on the ASTA (Application STA) thread.

If one of the tasks is canceled or throws an exception, the returned task will complete early, in the canceled state, and the exception, if one is encoutered, will be thrown if you call task::get or task::wait on that task.

Parameters

_Begin
The position of the first element in the range of elements to be combined into the resulting task.

_End
The position of the first element beyond the range of elements to be combined into the resulting task.

_TaskOptions_CancellationToken
The cancellation token which controls cancellation of the returned task. If you do not provide a cancellation token, the resulting task will receive the cancellation token of the task that causes it to complete.

Return Value

A task that completes successfully when any one of the input tasks has completed successfully. If the input tasks are of type T, the output of this function will be a task<std::pair<T, size_t>>>, where the first element of the pair is the result of the completing task, and the second element is the index of the task that finished. If the input tasks are of type void the output is a task<size_t>, where the result is the index of the completing task.

Remarks

when_any is a non-blocking function that produces a task as its result. Unlike task::wait, it is safe to call this function in a Windows 8.x Store app on the ASTA (Application STA) thread.