Execution

Execution

#include <sbio/core/execution.hh>

template<typenameDerived>
class Execution

Defined in src/lib/sbio/core/execution.hh:119

Subclassed by: PyExecution< BasePolicy >

The Execution policy is the central point for the management of IO activity.

The policy is used to control the StreamBroker life-cycle (transitioning through state machines), as well as the coordination of higher level abstractions, like the [BrokerGroup](api-sbio-BrokerGroup.md#brokergroup) and [DataSource](api-sbio-DataSource.md#datasource).

The policy has two overarching roles:

1. It builds open the state machine of the StreamBroker to control transitioning between various states. This leads to the definition of “hooks” that are close to one-to-one with the StreamBroker states, with some additional functionality incorporated to address the higher-level abstractions.
2. Coupled with a Storage class the policy provides for synchronization when using different parallelization strategies by defining a memory consistency model. When using an Execution policy for the parallelization strategies it supports, there is a guarantee that the data will be well syncrhonized and the program will be well formed.

For a simpler overview, to address the first role, we can consider that the policy defines hooks (in the form of static functions) to address the following state transitions of a StreamBroker:

The execution model defines the following hooks for customization corresponding to the broker stages above:

1. Allocation strategies are defined by the execution model. -> A broker implementation may request resources, and the file format will by definition provide minimums, but the final authority is the execution model.
2. Connection is unmanaged by the execution model.
3. Indexing stage contains 1 explicit hook: A switch to control whether the broker should index at all. The synchronizations hooks below will also be used.
4. For data access the policy defines 1 hook that controls whether the broker should proceed with retrieval (like stage 4 indexing above).

At the level of the BrokerGroup, the model provides control mechanisms for:

1. Allocation of BrokerGroup memory - principally, tables required for the management of the various Brokers under the umbrella of the Group.
2. The get_data hook determines how a Detector will distribute read and retrieval operations among potentially multiple brokers. A Detector may be gathering data together from multiple streams. This hook can control whether you read from all first, and then inspect for data, or proceed in order reading and inspecting, as an example. There is an equivalent function for requesting batches of data.

Finally, at the level of the DataSource, the following control points exist:

1. The execution model can determine how a DataSource distributes event/step indexing among parallel resources. (In whatever unit makes sense for the file format).

In addition to the above logical decisions, to address the second role, the policy has two main functions:

• pre_update
• post_update

These are used for resource synchronization immediately before and after a broker will touch any execution model managed memory. They can be used for synchronization when the policy is managing parallel processing units. E.g. for an MPI model, it may be used to implement fences and syncs on shared buffers across ranks. These are also used in conjunction with the concept of the StorageView which may invoke these automatically.

Template Parameters

• Derived The type of the sub-class Execution policy.

Public Static Attributes

Return	Name	Description
constexpr hd_std::bitset< static_cast< hd_std::size_t >(ParallelizationMethods::NUM_METHODS) >	ParallelSupport static constexpr	The set of parallelization methods supported by the Execution policy.

---

ParallelSupport

static constexpr

constexpr hd_std::bitset< static_cast< hd_std::size_t >(ParallelizationMethods::NUM_METHODS) > ParallelSupport { 0x0 }

Type: constexpr hd_std::bitset< static_cast< hd_std::size_t >(ParallelizationMethods::NUM_METHODS) >

Defined in src/lib/sbio/core/execution.hh:144

The set of parallelization methods supported by the Execution policy.

Public Static Methods

Return	Name	Description
constexprMemorySpace	result_memory_space static inline constexpr	The memory space that results (via get_data) are returned in.
SBIO_HDvoid	configure static inline
bool	validate_environment static inline	Verify that the runtime environment supports the EPolicy.
SBIO_HDauto	allocate_storage static inline requires FormatTraits<FTraits, IO, Derived>	Controls the allocation of storage.
SBIO_HDauto	allocate_storage static inline requires FormatTraits<FTraits, IO, Derived>
SBIO_HDvoid *	get_block_from_pool static inline
SBIO_HDbool	should_index static inline	Decide whether or not this StreamBroker should proceed to the indexing state.
SBIO_HD bool	should_process static inline	Decide whether or not this StreamBroker should process this particular step.
SBIO_HDDataResult	resolve_in_buffer static inline	Resolve a DataRequest for a StreamBroker into the indicated buffers.
SBIO_HDvoid	on_step static inline	An opportunity to provide explicit synchronization immediately after every step.
SBIO_HDvoid	pre_update static inline	An opportunity to provide explicit synchronization before any Storage changes.
SBIO_HDvoid	post_update static inline	An opportunity to provide explicit synchronization after any Storage changes.
SBIO_HDIOStatus	execute_read static inline
SBIO_HDvoid *	acquire_broker_view static inline
SBIO_HDvoid	publish_broker_view static inline	Publish bytes written to a view of a buffer.
constexprIOCapability	required_io_capabilities static inline constexpr	Query the capabiltiies this EPolicy requires for an IOPolicy to use it with.
SBIO_HDauto	allocate_group_storage static inline requires FormatTraits<FTraits, IO, Derived>
SBIO_HDIOStatus	get_data static inline	Run the data fetching and then querying of the filled buffers.
SBIO_HDIOStatus	fetch_then_get static inline	Default get_data, fetching for all units, then resolving fetched data.
SBIO_HDIOStatus	get_data_steps static inline	Run the data fetching and then querying of the filled buffers, for a BATCh of steps.
SBIO_HDIOStatus	fetch_then_get_steps static inline	Default get_data_steps, fetching for all units, then resolving fetched data.
SBIO_HD FTraits::StepIdxType	next static inline	Request the next step index to read data for.
SBIO_HDStepBatch< typename FTraits::StepIdxType >	next_batch static inline	Request the next contiguous batch of step indices to read data for.
SBIO_HDvoid	end_iteration static inline	Exit the iteration with state, releasing any held steps.

---

result_memory_space

static inline constexpr

constexpr static inline constexprMemorySpace result_memory_space()

Defined in src/lib/sbio/core/execution.hh:149

The memory space that results (via get_data) are returned in.

---

configure

static inline

template<classConfigT> static inline SBIO_HDvoid configure(constConfigT & config)

Defined in src/lib/sbio/core/execution.hh:162

---

validate_environment

static inline

template<classConfigT> static inline bool validate_environment(constConfigT & config, constchar *& error)

Defined in src/lib/sbio/core/execution.hh:183

Verify that the runtime environment supports the EPolicy.

The verification is run before the actual configuration. E.g., for MPI, it may be required that a certain thread level be supported by the MPI implementation.

Note

The function is used by the Context. By default there is nothing to validate.

Returns

true if the config can be used with the EPolicy in this environment.

Parameters

Parameter	Type	Description
config	constConfigT &	The configuration to use (if environment is validated).
error	constchar *&	A description of the problem if validation fails.

---

allocate_storage

static inline requires FormatTraits<FTraits, IO, Derived>

template<class IO, class FTraits> static inline SBIO_HDauto allocate_storage(AllocationRequest< FTraits > & request) requires FormatTraits<FTraits, IO, Derived>

Defined in src/lib/sbio/core/execution.hh:203

Controls the allocation of storage.

Returns

storage The storage object containing all buffers.

Parameters

Parameter	Type	Description
request	AllocationRequest< FTraits > &	A request from the stream broker for resources for each of the buffers it will need.

---

allocate_storage

static inline requires FormatTraits<FTraits, IO, Derived>

template<IsRequirementsList Requirements, class IO, class FTraits> static inline SBIO_HDauto allocate_storage(AllocationRequest< FTraits > & request) requires FormatTraits<FTraits, IO, Derived>

Defined in src/lib/sbio/core/execution.hh:210

---

get_block_from_pool

static inline

static inline SBIO_HDvoid * get_block_from_pool(std::size_t bytes, std::size_t alignment = 16)

Defined in src/lib/sbio/core/execution.hh:214

---

should_index

static inline

static inline SBIO_HDbool should_index()

Defined in src/lib/sbio/core/execution.hh:227

Decide whether or not this StreamBroker should proceed to the indexing state.

Returns

Whether the StreamBroker should proceed to the indexing state.

---

should_process

static inline

template<class FTraits> static inline SBIO_HD bool should_process(typename FTraits::StepIdxType & step_idx)

Defined in src/lib/sbio/core/execution.hh:243

Decide whether or not this StreamBroker should process this particular step.

Returns

Whether the StreamBroker should process this step.

Parameters

Parameter	Type	Description
step_idx	typename FTraits::StepIdxType &	The step to make the decision about.

---

resolve_in_buffer

static inline

template<class FTraits, class IO, classStorageT, classInventoryT> static inline SBIO_HDDataResult resolve_in_buffer(StorageT & storage, constInventoryT & inv, consttypename FTraits::DataRequest & req, PayloadOffsetCache & cache, typename FTraits::DataAccessPtn ptn, hd_std::size_t batch_idx)

Defined in src/lib/sbio/core/execution.hh:271

Resolve a DataRequest for a StreamBroker into the indicated buffers.

The StreamBroker can use this routine to offload the DataRequest to an EPolicy when it may need to resolve differences in MemorySpace between the data location and the buffers. E.g., a policy can implement handling on GPU.

Returns

The resolved data.

Parameters

Parameter	Type	Description
storage	StorageT &	The StreamBroker’s storage
inv	constInventoryT &	The StreamBroker’s MetadataInventory
req	consttypename FTraits::DataRequest &	The DataRequest for retrieval
ptn	typename FTraits::DataAccessPtn	The data access pattern for the fetched data (format-dependent)
batch_idx	hd_std::size_t	The step within a fetched batch.

---

on_step

static inline

static inline SBIO_HDvoid on_step(void * buffer)

Defined in src/lib/sbio/core/execution.hh:302

An opportunity to provide explicit synchronization immediately after every step.

Parameters

Parameter	Type	Description
buffer	void *	The underlying buffer which was filled by the step.

---

pre_update

static inline

template<classRole, classStorageT> static inline SBIO_HDvoid pre_update(StorageT & storage)

Defined in src/lib/sbio/core/execution.hh:314

An opportunity to provide explicit synchronization before any Storage changes.

Parameters

Parameter	Type	Description
storage	StorageT &	The StreamBroker’s storage which will be modified.

---

post_update

static inline

template<classRole, classStorageT, classSyncT> static inline SBIO_HDvoid post_update(StorageT & storage, SyncT && sync_vars, IOStatus status)

Defined in src/lib/sbio/core/execution.hh:334

An opportunity to provide explicit synchronization after any Storage changes.

For example, a policy may release locks, flush data, synchronize Windows etc.

Parameters

Parameter	Type	Description
storage	StorageT &	The StreamBroker’s storage which will be modified.
sync_vars	SyncT &&	Additional variables from a StreamBroker which may need synchronization.
status	IOStatus	The IOStatus result from the preceeding update.

---

execute_read

static inline

template<class AccessStyle> static inline SBIO_HDIOStatus execute_read()

Defined in src/lib/sbio/core/execution.hh:345

---

acquire_broker_view

static inline

template<typenameBuffer> static inline SBIO_HDvoid * acquire_broker_view(Buffer & buf)

Defined in src/lib/sbio/core/execution.hh:350

---

publish_broker_view

static inline

template<typenameBuffer> static inline SBIO_HDvoid publish_broker_view(Buffer & buf, void * view, hd_std::size_t nbytes)

Defined in src/lib/sbio/core/execution.hh:374

Publish bytes written to a view of a buffer.

Called after IO has written nbytes to the start of view, which is a view acquired from the the buffer buf.

If the current IO policy reads into a staging view (view), here they will be moved to the actual buffer (buf).

Note

By default, this is a no-op.

Parameters

Parameter	Type	Description
buf	Buffer &	The buffer the view is acquired from.
view	void *	The view used for the IO (e.g. staging).
nbytes	hd_std::size_t	The number of bytes into the view.

---

required_io_capabilities

static inline constexpr

template<typename IO> constexpr static inline constexprIOCapability required_io_capabilities()

Defined in src/lib/sbio/core/execution.hh:390

Query the capabiltiies this EPolicy requires for an IOPolicy to use it with.

By default, it requires reads to host memory, and concurrent reads if thread support is provided by the EPolicy.

Returns

The required set of capabilities.

---

allocate_group_storage

static inline requires FormatTraits<FTraits, IO, Derived>

template<class IO, class FTraits> static inline SBIO_HDauto allocate_group_storage(hd_std::size_t num_segments, hd_std::size_t max_batch_count = 1) requires FormatTraits<FTraits, IO, Derived>

Defined in src/lib/sbio/core/execution.hh:410

---

get_data

static inline

template<class FTraits, classFetchCBType, classGetCBType> static inline SBIO_HDIOStatus get_data(typename FTraits::StepIdxType step_idx, FetchCBType && unit_fetcher, hd_std::size_t num_fetches, GetCBType && unit_get_data, hd_std::size_t num_accesses)

Defined in src/lib/sbio/core/execution.hh:454

Run the data fetching and then querying of the filled buffers.

If the Derived class has not defined an implementation, in this case, the default behaviour will be to run all the fetch callbacks to fill the buffers, and then if all succeeded run each data retrieval in order afterwards.

Returns

The final IOStatus after having fetched all data and run the querying callbacks afterwards.

Parameters

Parameter	Type	Description
step_idx	typename FTraits::StepIdxType	The step to fetch data for.
unit_fetcher	FetchCBType &&	The callback used to perform an IO fetch for a single StreamBroker.
num_fetches	hd_std::size_t	The total number of fetches to perform.
unit_get_data	GetCBType &&	The callback used to read from a buffer after the fetch has been performed. Note that a single StreamBroker may end up being used multiple times via this callback if it must read from the buffer in different places.
num_accesses	hd_std::size_t	The total number of calls to unit_get_data to perform.

---

fetch_then_get

static inline

template<class FTraits, classFetchCBType, classGetCBType> static inline SBIO_HDIOStatus fetch_then_get(typename FTraits::StepIdxType step_idx, FetchCBType && unit_fetcher, hd_std::size_t num_fetches, GetCBType && unit_get_data, hd_std::size_t num_accesses)

Defined in src/lib/sbio/core/execution.hh:484

Default get_data, fetching for all units, then resolving fetched data.

---

get_data_steps

static inline

template<class FTraits, classFetchCBType, classGetCBType> static inline SBIO_HDIOStatus get_data_steps(const hd_std::initializer_list< typename FTraits::StepIdxType > & steps, FetchCBType && unit_fetcher, hd_std::size_t num_fetches, GetCBType && unit_get_data, hd_std::size_t num_accesses)

Defined in src/lib/sbio/core/execution.hh:533

Run the data fetching and then querying of the filled buffers, for a BATCh of steps.

If the Derived class has not defined an implementation, in this case, the default behaviour will be to run all the fetch callbacks to fill the buffers, and then if all succeeded run each data retrieval in order afterwards.

Returns

The final IOStatus after having fetched all data and run the querying callbacks afterwards.

Parameters

Parameter	Type	Description
steps	const hd_std::initializer_list< typename FTraits::StepIdxType > &	The batch of steps to fetch data for.
unit_fetcher	FetchCBType &&	The callback used to perform an IO fetch for a single StreamBroker.
num_fetches	hd_std::size_t	The total number of fetches to perform.
unit_get_data	GetCBType &&	The callback used to read from a buffer after the fetch has been performed. Note that a single StreamBroker may end up being used multiple times via this callback if it must read from the buffer in different places.
num_accesses	hd_std::size_t	The total number of calls to unit_get_data to perform.

---

fetch_then_get_steps

static inline

template<class FTraits, classFetchCBType, classGetCBType> static inline SBIO_HDIOStatus fetch_then_get_steps(const hd_std::initializer_list< typename FTraits::StepIdxType > & steps, FetchCBType && unit_fetcher, hd_std::size_t num_fetches, GetCBType && unit_get_data, hd_std::size_t num_accesses)

Defined in src/lib/sbio/core/execution.hh:563

Default get_data_steps, fetching for all units, then resolving fetched data.

---

next

static inline

template<class FTraits, classIterState, classIndexTrigger> static inline SBIO_HD FTraits::StepIdxType next(IterState & state, typename FTraits::StepIdxType & max_capacity, IndexTrigger && trigger)

Defined in src/lib/sbio/core/execution.hh:618

Request the next step index to read data for.

Returns

The index of the next step to read data for.

Parameters

Parameter	Type	Description
max_capacity	typename FTraits::StepIdxType &	The current max capacity that the StreamBroker has before reindexing is required. For data formats that do not support indexing, the max capacity will always be 1, and the reindexing callback may be a noop.
trigger	IndexTrigger &&	The callback to run to reindex upon reaching max_capacity, if applicable.

---

next_batch

static inline

template<class FTraits, classIterState, classIndexTrigger> static inline SBIO_HDStepBatch< typename FTraits::StepIdxType > next_batch(IterState & state, hd_std::size_t batch_size, typename FTraits::StepIdxType & max_capacity, IndexTrigger && trigger)

Defined in src/lib/sbio/core/execution.hh:655

Request the next contiguous batch of step indices to read data for.

Note

A batch is provided with a maximum size - it may be smaller, as it will not extend beyond the current maximum capactiy. This is because the batch cannot go over a reindexing trigger which by definition must be colelctive.

Returns

The next batch of steps, or an exhausted batch if no steps remain.

Parameters

Parameter	Type	Description
batch_size	hd_std::size_t	The maximum number of steps in the batch.
max_capacity	typename FTraits::StepIdxType &	The current max capacity that the StreamBroker has before reindexing is required. For data formats that do not support indexing, the max capacity will always be 1, and the reindexing callback may be a noop.
trigger	IndexTrigger &&	The callback to run to reindex upon reaching max_capacity.

---

end_iteration

static inline

template<class FTraits, classIterState, classIndexTrigger> static inline SBIO_HDvoid end_iteration(IterState & state, typename FTraits::StepIdxType & max_capacity, IndexTrigger && trigger)

Defined in src/lib/sbio/core/execution.hh:698

Exit the iteration with state, releasing any held steps.

A specific EPolicy should provide an implementation of this API if their model requires a parallely executing unit to hold in various locations, most often for reindexing, until other outsstanding steps are released. In the absence of this API, an early exit from an iteration will cause hangs. E.g., useful in thread-based policies.

The capacity and reindex trigger are passed like with the next API. A Policy may require that an executing unit continue to participate in reindexing even after the unit itself has exhausted its step indices. However, this is policy dependent, so it may implement a simpler API using only the state.

Note

An EPolicy may implment end_iteration_impl<FTraits>(state, max_cap, trigger) OR, alternatively, end_iteration_impl<FTraits>(state), if it implements the API at all.

Parameters

Parameter	Type	Description
max_capacity	typename FTraits::StepIdxType &	The current max capacity.
trigger	IndexTrigger &&	The reindex callback to run.

Public Types

Name	Description
BufferTypeFor	Sub-classes must define the used buffer types.

---

BufferTypeFor

using BufferTypeFor = void

Type: void

Defined in src/lib/sbio/core/execution.hh:125

Sub-classes must define the used buffer types.