Execution Policies

Detailed Description

Execution policies describe the execution properties of bulk tasks created by control structures such as bulk_invoke(). Such properties include both how and where execution should occur. Forward progress requirements encapsulated by execution policies describe the ordering relationships of individual execution agents comprising a bulk task, while the execution policy's associated executor governs where those execution agents execute.

Essential Characteristics

An execution policy collects two essential characteristics: a type of execution agent defining execution requirements, and an associated executor which creates execution with prescribed guarantees. When combined with control structures like bulk_invoke(), the associated executor creates execution and the characteristics of this execution are reified in the program as execution agent objects.

Parameterization

Aside from these characteristics, execution policy objects also encapsulate a parameterization describing the group of execution agents to create when composed with a control structure. For most of Agency's execution agent types, these parameters define the range of indices assigned to agents in the group.

An existing instance of an execution policy may be called like a function to produce a different an instance with a different parameterization. For example, the execution policy agency::par may be called like a function to create a new policy with a different parameterization:

// call seq like a function to produce an execution policy generating 13 agents
agency::bulk_invoke(agency::seq(13), [](agency::sequenced_agent& self)
{
  std::cout << self.index() << std::endl;
});

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

Alternatively, we can shift the origin of the group by passing agency::seq a half-open range:

agency::bulk_invoke(agency::seq(10,23), [](agency::sequenced_agent& self)
{
  std::cout << self.index() << std::endl;
});

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

The associated executor

Each of Agency's execution policies have an associated executor. The member function .executor() provides access to this executor:

// make a copy of par's associated executor
agency::parallel_executor par_exec = agency::par.executor();

The type of an execution policy's associated executor is named by the member type executor_type. Generic contexts such as templates may use this type:

template<class ExecutionPolicy>
void foo(ExecutionPolicy& policy)
{
  // use the member type executor_type to make a copy of policy's associated executor
  typename ExecutionPolicy::executor_type exec1 = policy.executor();

  // alternatively, use auto
  auto exec2 = policy.executor();

  ...
}

Replacing an executor with .on()

An existing execution policy's associated executor may be replaced with the .on() member function. .on() creates a new execution policy object whose associated executor is a copy of the given executor:

// suppose I have some existing executor
agency::sequenced_executor my_executor;

// associate my_executor with a new policy derived from agency::par
auto new_policy = agency::par.on(my_executor);

// now all execution generated by new_policy will be created "on" my_executor

Classes
class	agency::basic_execution_policy< ExecutionAgent, Executor, DerivedExecutionPolicy >
	The basic type from which all of Agency's execution policies derive their common functionality. More...
class	agency::sequenced_execution_policy
	Encapsulates requirements for creating groups of sequenced execution agents. More...
class	agency::concurrent_execution_policy
	Encapsulates requirements for creating groups of concurrent execution agents. More...
class	agency::parallel_execution_policy
	Encapsulates requirements for creating groups of parallel execution agents. More...
class	agency::unsequenced_execution_policy
	Encapsulates requirements for creating groups of unsequenced execution agents. More...

Variables
constexpr sequenced_execution_policy	agency::seq {}
	The global variable seq is the default sequenced_execution_policy.
constexpr concurrent_execution_policy	agency::con {}
	The global variable con is the default concurrent_execution_policy.
const parallel_execution_policy	agency::par {}
	The global variable par is the default parallel_execution_policy.
constexpr unsequenced_execution_policy	agency::unseq {}
	The global variable unseq is the default unsequenced_execution_policy.