Execution

Execution

#include <sbio/core/execution.hh>

template<typenameDerived>
class Execution

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

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.

List of all members

Name	Kind	Owner
ParallelSupport	variable	Declared here
result_memory_space	function	Declared here
configure	function	Declared here
allocate_storage	function	Declared here
allocate_storage	function	Declared here
get_block_from_pool	function	Declared here
should_index	function	Declared here
should_process	function	Declared here
on_step	function	Declared here
pre_update	function	Declared here
post_update	function	Declared here
execute_read	function	Declared here
acquire_broker_view	function	Declared here
allocate_group_storage	function	Declared here
get_data	function	Declared here
get_data_steps	function	Declared here
next	function	Declared here
BufferTypeFor	typedef	Declared here

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 }

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

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
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_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_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	get_data_steps static inline	Run the data fetching and then querying of the filled buffers, for a BATCh of steps.
SBIO_HD FTraits::StepIdxType	next static inline	Request the next step index to read data for.

---

result_memory_space

static inline constexpr

constexpr static inline constexprMemorySpace result_memory_space()

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

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:150

---

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:168

Controls the allocation of storage.

Returns

storage The storage object containing all buffers.

Parameters

Parameter	Type	Description
request	[AllocationRequest](api-sbio-AllocationRequest.md#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<IsTypeList 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:175

---

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:179

---

should_index

static inline

static inline SBIO_HDbool should_index()

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

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:208

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.

---

on_step

static inline

static inline SBIO_HDvoid on_step(void * buffer)

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

An opportunity to provide explicit synchronization immediately after every step.

Parameters

Parameter	Type	Description
buffer	[void](#should_process) *	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:233

An opportunity to provide explicit synchronization before any Storage changes.

Parameters

Parameter	Type	Description
storage	[StorageT](#should_process) &	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:253

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](#should_process) &	The StreamBroker’s storage which will be modified.
sync_vars	[SyncT](#should_process) &&	Additional variables from a StreamBroker which may need synchronization.
status	[IOStatus](api-sbio.md#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:264

---

acquire_broker_view

static inline

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

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

---

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:281

---

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:325

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](#should_process) FTraits::StepIdxType	The step to fetch data for.
unit_fetcher	[FetchCBType](#should_process) &&	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](#should_process) &&	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.

---

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:386

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](#should_process) hd_std::initializer_list< [typename](#should_process) FTraits::StepIdxType > &	The batch of steps to fetch data for.
unit_fetcher	[FetchCBType](#should_process) &&	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](#should_process) &&	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.

---

next

static inline

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

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

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](#should_process) 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](#should_process) &&	The callback to run to reindex upon reaching max_capacity, if applicable.

Public Types

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

---

BufferTypeFor

using BufferTypeFor = void

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

Sub-classes must define the used buffer types.