agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy > Class Template Reference

The basic type from which all of Agency's execution policies derive their common functionality. More...

Inherited by agency::cuda::experimental::static_concurrent_execution_policy< group_size, grain_size >, agency::experimental::static_concurrent_execution_policy< group_size, grain_size >, and agency::experimental::static_sequenced_execution_policy< group_size, grain_size >.

Public Types
using	execution_agent_type = ExecutionAgent
	The type of execution agent associated with this basic_execution_policy.
using	executor_type = Executor
	The type of executor associated with this basic_execution_policy.
using	param_type = typename execution_agent_traits< execution_agent_type >::param_type
	The type of this execution policy's parameterization.

Public Member Functions
	basic_execution_policy ()=default
	The default constructor default constructs this execution policy's associated executor and parameterization.
	basic_execution_policy (const param_type &param, const executor_type &executor=executor_type{})
	This constructor constructs a new basic_execution_policy given a parameterization and executor. More...
const param_type &	param () const
	Returns this execution policy's parameterization.
executor_type &	executor () const
	Returns this execution policy's associated executor.
template<class OtherExecutor >
auto	on (const OtherExecutor &exec) const -> decltype(replace_executor(*this, exec))
	Replaces this execution policy's executor with another. More...
template<class Arg1 , class... Args>
see_below	operator() (Arg1 &&arg1, Args &&...args) const
	Reparameterizes this execution policy. More...

Detailed Description

template<class ExecutionAgent, class Executor, class DerivedExecutionPolicy>
class agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy >

basic_execution_policy defines the essential functionality which all of Agency's execution policies share in common. Because all of Agency's execution policy types publicly inherit from basic_execution_policy, the documentation for their common, public functionality is collected here.

basic_execution_policy may also be used to define custom execution policy types by instantiating basic_execution_policy with an execution agent type and an executor type. Either of these types may be user-defined.

Template Parameters

ExecutionAgent	The type of execution agent created by the basic_execution_policy.
Executor	The type of executor associated with the basic_execution_policy.
DerivedExecutionPolicy	The name of the execution policy deriving from this basic_execution_policy. void indicates that no execution policy will be derived from this basic_execution_policy.

Constructor & Destructor Documentation

template<class ExecutionAgent, class Executor, class DerivedExecutionPolicy>

agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy >::basic_execution_policy ( const param_type &  param, const executor_type &  executor = executor_type{}  )

inline

Parameters

param	The parameterization of this basic_execution_policy.
executor	The executor to associate with this basic_execution_policy.

Member Function Documentation

template<class ExecutionAgent, class Executor, class DerivedExecutionPolicy>

template<class OtherExecutor >

auto agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy >::on ( const OtherExecutor &  exec ) const -> decltype(replace_executor(*this, exec))

inline

on() returns a new execution policy identical to *this but whose associated executor has been replaced by another executor.

For example, we can require an otherwise parallel task to execute sequentially in the current thread by executing the task on a sequenced_executor:

agency::sequenced_executor seq_exec;

// require the parallel_agents induced by par to execute sequentially on seq_exec
agency::bulk_invoke(agency::par(10).on(seq_exec), [](agency::parallel_agent& self)
{
  std::cout << self.index() << std::endl;
});

// the integers [0,10) are printed in sequence

Note that using on() does not change the type of execution agent object created by the policy; it only changes the underlying physical execution of these agents. The relative forward progress characteristics of the execution agents required by the execution policy and the forward progress guarantees must make sense; the forward progress guarantees made by the executor may not weaken the requirements of the policy. A program that attempts to do this is ill-formed and will not compile. In this example's case, because agency::sequenced_executor makes a stronger guarantee (sequenced execution) than does agency::par (parallel execution), the program is well-formed.

Parameters

exec	The other executor to associate with the returned execution policy.

Returns

An execution policy equivalent to *this but whose associated executor is a copy of exec. The type of the result is an execution policy type Policy with the following characteristics:

• Policy::execution_agent_type is execution_agent_type,
• Policy::param_type is param_type
• Policy::executor_type is OtherExecutor.

Note

The given executor's forward progress guarantees must not be weaker than this execution policy's forward progress requirements.

on() is sugar for the expression replace_executor(*this, exec).

See also

replace_executor

template<class ExecutionAgent, class Executor, class DerivedExecutionPolicy>

template<class Arg1 , class... Args>

see_below agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy >::operator() ( Arg1 &&  arg1, Args &&...  args  ) const

inline

operator() returns a new execution policy identical to *this but whose parameterization is constructed from the given arguments.

Parameters

arg1	The first argument to forward to param_type's constructor.
args	The rest of the arguments to forward to param_type's constructor.

Returns

An execution policy equivalent to *this but whose parameterization has been constructed from the given arguments. The type of the result is:

• DerivedExecutionPolicy, when DerivedExecutionPolicy is not void
• basic_execution_policy<ExecutionAgent,Executor,void>, otherwise.