BrokerGroup

BrokerGroup

#include <sbio/core/broker_group.hh>

template<IsStreamBroker BrokerType, FormatTraits< typename BrokerType::IOPolicy, typename BrokerType::ExecutionPolicy > FTraits, std::size_t MaxSegments = 128>
class BrokerGroup

Defined in src/lib/sbio/core/broker_group.hh:69

The logical grouping of StreamBrokers which should be queried together.

While the StreamBroker represents the smallest logical unit that makes sense to query data for, the BrokerGroup represents the combination of various StreamBrokers. Frequently, it makes more sense at higher levels of abstraction to consider a group of StreamBrokers together as a single unit. For example, each StreamBroker may be managing only a portion of a larger data construct (a part of an image, e.g.). The BrokerGroup then provides a single interface to query all logically related StreamBrokers simulatneously. Note that a StreamBroker may belong to multiple BrokerGroups.

Template Parameters

• BrokerType The type of the underlying StreamBroker in the group.

• FTraits The data format being read.

• MaxSegments The maximum number of members in the group.

Public Methods

Return	Name	Description
	BrokerGroup	Defaulted constructor.
	BrokerGroup inline
	BrokerGroup inline
void	set_step_mapping inline	Configure and set the step remapping policy for the managed SegmentRefs.
const char *	group_name const inline
const char *	group_type const inline
std::size_t	num_segments const inline
const DataSegmentRef *	segments const inline
const DataSegmentRef &	segment const inline
BrokerType **	stream_brokers inline
SBIO_HD std::size_t	num_stream_brokers const inline
SBIO_HDIOStatus	fetch_next_for const inline
SBIO_HDIOStatus	fetch_steps_for const inline	Fetch a batch of the group’s steps for a StreamBrokerbroker_no.
SBIO_HDDataResult	get_data_for const inline
SBIO_HDDataResult	get_data_for const inline
ncarray::SOViewFor< MemTag >	get_data const inline requires std::invocable<CBType, DataResult>	Fetch data for a given index AND read into the fetched data to pull specific data out.
ncarray::SOViewFor< MemTag >	get_data const inline	Fetch data for a given index AND read into the fetched data to pull specific data out.
SBIO_HD ncarray::SOViewFor< MemTag >	resolve_data const inline	Resolve data for a step from the already fetched buffers, without any IO.
SBIO_HD bool	shares_fetch const inline	Whether a fetch for this group’s StreamBrokerbroker_no and a fetch for the other group’s StreamBrokerother_no fill the same buffer with the same step.
SBIO_HD bool	shares_buffer const inline	Check if a fetch for broker_no fills the same buffer as other’s other_no.
SBIO_HDIOStatus	fetch_range_for const inline	Get the range of steps for a StreamBroker that correspond to a group’s range.
ncarray::SOViewFor< MemTag >	get_multi_data const inline requires std::invocable<CBType, DataResult>
ncarray::SOViewFor< MemTag >	get_multi_data const inline
SBIO_HD ncarray::SOViewFor< MemTag >	resolve_multi_data const inline	Resolve data for a contiguous batch of steps [first, last) from the already fetched buffers, without any IO.

---

BrokerGroup

BrokerGroup() = default

Defined in src/lib/sbio/core/broker_group.hh:158

Defaulted constructor.

---

BrokerGroup

inline

inline BrokerGroup(const char * name, const char * type, std::size_t num_segments, DataSegmentRef * segments)

Defined in src/lib/sbio/core/broker_group.hh:160

---

BrokerGroup

inline

inline BrokerGroup(const GroupTopology< BrokerType, MaxSegments > & topo)

Defined in src/lib/sbio/core/broker_group.hh:237

---

set_step_mapping

inline

inline void set_step_mapping(StepMapping mapping, DataAccessPtn align_to = {})

Defined in src/lib/sbio/core/broker_group.hh:257

Configure and set the step remapping policy for the managed SegmentRefs.

Parameters

Parameter	Type	Description
mapping	StepMapping	The mapping policy to use.
align_to	DataAccessPtn	The pattern to align to if using an aligning policy.

---

group_name

const inline

inline const char * group_name() const

Defined in src/lib/sbio/core/broker_group.hh:262

---

group_type

const inline

inline const char * group_type() const

Defined in src/lib/sbio/core/broker_group.hh:263

---

num_segments

const inline

inline std::size_t num_segments() const

Defined in src/lib/sbio/core/broker_group.hh:265

---

segments

const inline

inline const DataSegmentRef * segments() const

Defined in src/lib/sbio/core/broker_group.hh:266

---

segment

const inline

inline const DataSegmentRef & segment(std::size_t i) const

Defined in src/lib/sbio/core/broker_group.hh:273

---

stream_brokers

inline

inline BrokerType ** stream_brokers()

Defined in src/lib/sbio/core/broker_group.hh:277

---

num_stream_brokers

const inline

inline SBIO_HD std::size_t num_stream_brokers() const

Defined in src/lib/sbio/core/broker_group.hh:284

---

fetch_next_for

const inline

inline SBIO_HDIOStatus fetch_next_for(StepIdxType & step_idx, std::size_t broker_no) const

Defined in src/lib/sbio/core/broker_group.hh:286

---

fetch_steps_for

const inline

inline SBIO_HDIOStatus fetch_steps_for(std::initializer_list< StepIdxType > steps, std::size_t broker_no) const

Defined in src/lib/sbio/core/broker_group.hh:310

Fetch a batch of the group’s steps for a StreamBrokerbroker_no.

Note

When using [StepMapping::AlignTo](api-sbio.md#namespacesbio_1acb65bdb803043bf5031e01c8c1dbf952a7518d668dcf9d326702c5e9e29c3b47d), a StreamBroker of another access pattern fetches the range that must be mapped onto. Then the alignment is done.

Returns

The IOStatus for the fetch.

Parameters

Parameter	Type	Description
steps	std::initializer_list< StepIdxType >	The batch of steps [first, last)
broker_no	std::size_t	The StreamBroker to fetch for.

---

get_data_for

const inline

template<class CBType> inline SBIO_HDDataResult get_data_for(DataRequest & req, std::size_t segment_no, CBType && callback, std::size_t batch_idx = 0) const

Defined in src/lib/sbio/core/broker_group.hh:336

---

get_data_for

const inline

inline SBIO_HDDataResult get_data_for(DataRequest & req, std::size_t segment_no, std::size_t batch_idx = 0) const

Defined in src/lib/sbio/core/broker_group.hh:356

---

get_data

const inline requires std::invocable<CBType, DataResult>

template<class CBType, typename... Args> inline ncarray::SOViewFor< MemTag > get_data(StepIdxType & step_idx, CBType && callback, Args &&... args) const requires std::invocable<CBType, DataResult>

Defined in src/lib/sbio/core/broker_group.hh:392

Fetch data for a given index AND read into the fetched data to pull specific data out.

NOTE: We add the concept restricting the CBType to invocable to avoid overload ambiguities. This is likely not needed, as the partial ordering will treat the Args pack as less-specialized, and prefer this overload. Adding it, though, does not hurt and future-proofs against future overloads.

Returns

array The requested data as an SOArrayView or SODevArrayView depending on whether MemTag is HostTag or DevTag, respectively.

Parameters

Parameter	Type	Description
step_idx	StepIdxType &	The index for the data to fetch.
callback	CBType &&	Optionally provide a callback to be run on every segment independently before the data is combined.
args	Args &&...	The arguments for the DataRequest constructor.

---

get_data

const inline

template<typename... Args> inline ncarray::SOViewFor< MemTag > get_data(StepIdxType & step_idx, Args &&... args) const

Defined in src/lib/sbio/core/broker_group.hh:508

Fetch data for a given index AND read into the fetched data to pull specific data out.

This is an identical get_data call to the other overload, without the application of a lambda callback.

Returns

array The requested data as an SOArrayView or SODevArrayView depending on whether MemTag is HostTag or DevTag, respectively.

Parameters

Parameter	Type	Description
step_idx	StepIdxType &	The index for the data to fetch.
args	Args &&...	The arguments for the DataRequest constructor.

---

resolve_data

const inline

template<typename... Args> inline SBIO_HD ncarray::SOViewFor< MemTag > resolve_data(const StepIdxType & step_idx, Args &&... args) const

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

Resolve data for a step from the already fetched buffers, without any IO.

This is the data resolution half of get_data. The step’s data must already be in the StreamBrokers’ buffers, e.g. fetched with fetch_next_for (directly or via a zipped iteration). As with get_data, the result is valid until the next fetch into the same buffers.

Returns

array The requested data as an SOArrayView or SODevArrayView depending on whether MemTag is HostTag or DevTag, respectively.

Parameters

Parameter	Type	Description
step_idx	const StepIdxType &	The index of the (already fetched) step.
args	Args &&...	The arguments for the DataRequest constructor.

---

shares_fetch

const inline

inline SBIO_HD bool shares_fetch(std::size_t broker_no, const BrokerGroup & other, std::size_t other_no) const

Defined in src/lib/sbio/core/broker_group.hh:679

Whether a fetch for this group’s StreamBrokerbroker_no and a fetch for the other group’s StreamBrokerother_no fill the same buffer with the same step.

This is the case when both use the same StreamBroker, with the same access pattern and the same step mapping. A zipped iteration then only fetches once.

Returns

Whether the two fetches are identical.

Parameters

Parameter	Type	Description
broker_no	std::size_t	The StreamBroker of this group.
other	const BrokerGroup &	The other group.
other_no	std::size_t	The StreamBroker of the other group.

---

shares_buffer

const inline

inline SBIO_HD bool shares_buffer(std::size_t broker_no, const BrokerGroup & other, std::size_t other_no) const

Defined in src/lib/sbio/core/broker_group.hh:705

Check if a fetch for broker_no fills the same buffer as other’s other_no.

Note

This occurs when both BrokerGroups use the same StreamBroker and access pattern. If using different step mappings (see shares_fetch), they may need different steps in the buffer.

Returns

Whether the fetches fill the same buffer.

Parameters

Parameter	Type	Description
broker_no	std::size_t	The StreamBroker broker number for this BrokerGroup.
other	const BrokerGroup &	The other BrokerGroup.
other_no	std::size_t	The StreamBroker broker number for the otherBrokerGroup.

---

fetch_range_for

const inline

inline SBIO_HDIOStatus fetch_range_for(StepIdxType first, StepIdxType last, std::size_t broker_no, std::size_t & first_ordinal, std::size_t & end_ordinal) const

Defined in src/lib/sbio/core/broker_group.hh:727

Get the range of steps for a StreamBroker that correspond to a group’s range.

Note

If there is no step alignment occurring, then the two ranges are identical and this is a normal fetch. Otherwise, it is a fetch over the range that the steps map onto.

Returns

Whether the steps could be mapped.

---

get_multi_data

const inline requires std::invocable<CBType, DataResult>

template<class CBType, typename... Args> inline ncarray::SOViewFor< MemTag > get_multi_data(const std::initializer_list< StepIdxType > & steps, CBType && callback, Args &&... args) const requires std::invocable<CBType, DataResult>

Defined in src/lib/sbio/core/broker_group.hh:748

---

get_multi_data

const inline

template<typename... Args> inline ncarray::SOViewFor< MemTag > get_multi_data(const std::initializer_list< StepIdxType > & steps, Args &&... args) const

Defined in src/lib/sbio/core/broker_group.hh:836

---

resolve_multi_data

const inline

template<typename... Args> inline SBIO_HD ncarray::SOViewFor< MemTag > resolve_multi_data(const StepIdxType & first, const StepIdxType & last, Args &&... args) const

Defined in src/lib/sbio/core/broker_group.hh:936

Resolve data for a contiguous batch of steps [first, last) from the already fetched buffers, without any IO.

This is the data resolution half of get_multi_data. The batch’s data must already be in the StreamBrokers’ buffers, e.g. fetched with fetch_steps_for (directly or via a zipped iteration over batches). The result always has a batch axis.

Returns

array The requested data as an SOArrayView or SODevArrayView depending on whether MemTag is HostTag or DevTag, respectively.

Parameters

Parameter	Type	Description
first	const StepIdxType &	The first step of the (already fetched) batch.
last	const StepIdxType &	One past the last step of the batch.
args	Args &&...	The arguments for the DataRequest constructor.

Public Static Attributes

Return	Name	Description
constexpr std::size_t	SegmentCapacity static constexpr	The maximum number of segments (and therefore StreamBrokers) in the BrokerGroup.

---

SegmentCapacity

static constexpr

constexpr std::size_t SegmentCapacity { MaxSegments }

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

The maximum number of segments (and therefore StreamBrokers) in the BrokerGroup.

Public Types

Name	Description
IOPolicy	The type of the IO strategy being used.
ExecutionPolicy	The Execution policy type.
DataFormat	The type of data being read.
StreamType	The type of Stream: I.e., the IO strategy and data format being read.
SBStorageType	The type of the StreamBroker’s Storage.
EPolicyConfig	The Execution policy configuration object type.
StreamConfig	The individual Stream configuration object type.
StreamMetadata	The type of the general metadata object for the data format’s Stream.
DataAccessPtn	The type of the enumerator used to specify access patterns used for the format.
DataRequest	The type of a request object used to query for data.
StepIdxType	The type used to request a specific step from the Stream.
PtrTableRequirements
PtrStorageType
MemTag	Based on choice of ExecutionPolicy, data will return in host or device buffers.
DataSegmentRef

---

IOPolicy

using IOPolicy = typename BrokerType::IOPolicy

Defined in src/lib/sbio/core/broker_group.hh:74

The type of the IO strategy being used.

---

ExecutionPolicy

using ExecutionPolicy = typename BrokerType::ExecutionPolicy

Defined in src/lib/sbio/core/broker_group.hh:78

The Execution policy type.

---

DataFormat

using DataFormat = FTraits

Defined in src/lib/sbio/core/broker_group.hh:82

The type of data being read.

---

StreamType

using StreamType = Stream< IOPolicy, FTraits >

Type: Stream< IOPolicy, FTraits >

Defined in src/lib/sbio/core/broker_group.hh:87

The type of Stream: I.e., the IO strategy and data format being read.

---

SBStorageType

using SBStorageType = Storage< typename FTraits::BrokerBufferRequirements, ExecutionPolicy >

Type: Storage< typename FTraits::BrokerBufferRequirements, ExecutionPolicy >

Defined in src/lib/sbio/core/broker_group.hh:92

The type of the StreamBroker’s Storage.

---

EPolicyConfig

using EPolicyConfig = typename ExecutionPolicy::Config

Defined in src/lib/sbio/core/broker_group.hh:104

The Execution policy configuration object type.

epolicy_config objects configure the global behaviour of the Execution policy being used. The Execution policy must be configured before any Streams are opened as it controls all aspects of IO down to the allocation of Storage.

---

StreamConfig

using StreamConfig = typename FTraits::StreamParameters

Defined in src/lib/sbio/core/broker_group.hh:111

The individual Stream configuration object type.

stream_config objects are used to set up each individual Stream so that it can connect and read from its individual data.

---

StreamMetadata

using StreamMetadata = MetadataInventory< FTraits >

Type: MetadataInventory< FTraits >

Defined in src/lib/sbio/core/broker_group.hh:116

The type of the general metadata object for the data format’s Stream.

---

DataAccessPtn

using DataAccessPtn = typename FTraits::DataAccessPtn

Defined in src/lib/sbio/core/broker_group.hh:121

The type of the enumerator used to specify access patterns used for the format.

---

DataRequest

using DataRequest = typename FTraits::DataRequest

Defined in src/lib/sbio/core/broker_group.hh:129

The type of a request object used to query for data.

---

StepIdxType

using StepIdxType = typename FTraits::StepIdxType

Defined in src/lib/sbio/core/broker_group.hh:136

The type used to request a specific step from the Stream.

This type is required and guaranteed to be convertible std::size_t; however, different data format’s may use different underlying types.

---

PtrTableRequirements

using PtrTableRequirements = RequirementsList< BufferDescriptor< roles::Table, 0, sizeof(void *)> >

Type: RequirementsList< BufferDescriptor< roles::Table, 0, sizeof(void *)> >

Defined in src/lib/sbio/core/broker_group.hh:138

---

PtrStorageType

using PtrStorageType = Storage< PtrTableRequirements, ExecutionPolicy >

Type: Storage< PtrTableRequirements, ExecutionPolicy >

Defined in src/lib/sbio/core/broker_group.hh:140

---

MemTag

using MemTag = std::conditional_t< ExecutionPolicy::result_memory_space()==MemorySpace::Host, ncarray::HostTag, ncarray::DevTag >

Type: std::conditional_t< ExecutionPolicy::result_memory_space()==MemorySpace::Host, ncarray::HostTag, ncarray::DevTag >

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

Based on choice of ExecutionPolicy, data will return in host or device buffers.

As data is returned via ncarray array objects, the MemTag converts a MemorySpace indicator in sbio to the tagging system used for host/device array constructs in ncarray.

---

DataSegmentRef

using DataSegmentRef = SegmentRef< BrokerType >

Type: SegmentRef< BrokerType >

Defined in src/lib/sbio/core/broker_group.hh:155

Private Attributes

Return	Name	Description
const void *	m_ptrs
GroupTopology< BrokerType, MaxSegments >	m_topology
PtrStorageType	m_ptr_storage

---

m_ptrs

const void * m_ptrs[MaxSegments]

Defined in src/lib/sbio/core/broker_group.hh:984

---

m_topology

GroupTopology< BrokerType, MaxSegments > m_topology

Type: GroupTopology< BrokerType, MaxSegments >

Defined in src/lib/sbio/core/broker_group.hh:1069

---

m_ptr_storage

PtrStorageType m_ptr_storage

Type: PtrStorageType

Defined in src/lib/sbio/core/broker_group.hh:1071

Private Methods

Return	Name	Description
SBIO_HD bool	is_aligned const inline	Whether a particular segment’s steps are being aligned to a different access pattern.
SBIO_HDIOStatus	map_batch const inline	Remap a segment’s steps onto the batch of steps for the access pattern its aligend to.
SBIO_HD std::size_t	batch_slot const inline	Determined where a step first + cnt is within a fetched batch of steps.

---

is_aligned

const inline

inline SBIO_HD bool is_aligned(const DataSegmentRef & seg) const

Defined in src/lib/sbio/core/broker_group.hh:992

Whether a particular segment’s steps are being aligned to a different access pattern.

Note

This alignment is only available when using the StreamBroker’s generic indexing routines (or, at least, we can only know if its being done)

---

map_batch

const inline

inline SBIO_HDIOStatus map_batch(const DataSegmentRef & seg, StepIdxType first, StepIdxType last, std::size_t & first_ordinal, std::size_t & end_ordinal) const

Defined in src/lib/sbio/core/broker_group.hh:1019

Remap a segment’s steps onto the batch of steps for the access pattern its aligend to.

This maps [first_ordinal, end_ordinal) onto [first, last) that the segment was configured to align to.

Note

The mapping is monotonic and runs from the ordinal of first to the ordinal of last - 1.

Note

Several steps may map to the same ordinal. In that case, it will only actually be fetched once.

Note

If the segment’s steps are more frequent than those of the pattern it’s being aligned to, the remapped range may end up being longer than the configured max batch size. It wouldn’t fit into the Data buffer in that case and a PayloadTruncatedError would be returned.

---

batch_slot

const inline

inline SBIO_HD std::size_t batch_slot(std::size_t segment_no, StepIdxType first, std::size_t cnt) const

Defined in src/lib/sbio/core/broker_group.hh:1050

Determined where a step first + cnt is within a fetched batch of steps.

If there are no step raemapping then its just cnt. If AlignTo was configured though, then the remap must be considered and its the ordinal relative to the first remapped ordinal.