Description

template<typename T>
class tcspc::bucket< T >

Value-semantic container for array data allowing use of custom storage.

A bucket may be used as an event type (as in the output of tcspc::batch or tcspc::read_binary_stream), or as a field in another event (as in the histogram events).

Bucket instances are obtained from a tcspc::bucket_source (see Bucket sources).

A bucket implements, among other things, an interface similar to std::span, allowing it to be treated as a contiguous container of T objects.

Copying a bucket copies the data into newly allocated memory. This should be avoided in production code, but is convenient for testing of processors that emit buckets.

Moving a bucket transfers both its data and underlying storage to the destination.

A bucket holds a storage, which can carry ownership or information about the bucket's underlying storage. The type of the storage is dependent on the bucket source (it is stored in the bucket in a type-erased form). Where supported by the bucket source, the storage has a known type and can be observed or extracted from a bucket, recovering direct access to the underlying storage.

A default-constructed bucket is empty and has no observable or extractable storage.

Comparing two buckets for equality (==) or inequality (!=) returns whether the data is equal or not (note that this differs from std::span). Together with the copy behavior, this makes bucket<T> a regular type.

Processors emitting buckets are typically constructed by passing in the bucket source. They should emit buckets (or events containing buckets) by const reference when letting the downstream observe the bucket contents before the processor finishes filling them. Finished buckets should be emitted by rvalue reference (std::move) so that the downstream processor can extract the storage if it so desires. Processors that emit a sequence of buckets in these ways should document the semantics of the sequence, and (usually) obtain buckets from the provided bucket source in the exact order in which they are emitted.

Buckets of const elements (T is const-qualified) are sometimes used to construct views of const data. Aside from being read-only, these buckets behave the same way as bucket-of-non-const: they can be moved around preserving their storage and thus avoid copying their data.

Note that bucket<T> does not implicitly convert to bucket<T const>, unlike with std::span, because that would require copying or moving the storage.

Ways to emit buckets (for T non-const):

As bucket<T> const &: read-only data with no transferrable storage (ad-hoc buckets are always emitted this way).
As bucket<T> &&: read-write data with transferrable storage (also allows moving out elements of the bucket).
As bucket<T const> &&: read-only data with transferrable storage (for propagating read-only data without copying).
As bucket<T const> const &: we avoid this, preferring to emit bucket<T> const &.

Handlers accepting buckets (as with any other event type) should always accept bucket<T> const &. In addition, they should accept bucket<T const> const &. Optionally they may also accept bucket<T> && and/or bucket<T const> && if they benefit from being able to transfer the bucket storage or, in the case of bucket<T> &&, being able to move out the bucket elements.

Template Parameters

T	element type of the data array carried by the bucket

Public Types
using	const_iterator = typename std::span<T const>::iterator
	Const iterator type.
using	const_pointer = typename std::span<T>::const_pointer
	Element const pointer type.
using	const_reference = typename std::span<T>::const_reference
	Element const reference type.
using	const_reverse_iterator
	Const reverse iterator type.
using	difference_type = typename std::span<T>::difference_type
	Difference type.
using	element_type = typename std::span<T>::element_type
	Element type.
using	iterator = typename std::span<T>::iterator
	Iterator type.
using	pointer = typename std::span<T>::pointer
	Element pointer type.
using	reference = typename std::span<T>::reference
	Element reference type.
using	reverse_iterator = typename std::span<T>::reverse_iterator
	Reverse iterator type.
using	size_type = typename std::span<T>::size_type
	Size type.
using	value_type = typename std::span<T>::value_type
	Value type.

Public Member Functions
	bucket () noexcept=default
	Construct an empty bucket.
	bucket (bucket &&other) noexcept=default
	Move constructor.
	bucket (bucket const &other)
	Copy constructor (allocates new private storage).
template<typename S>
	bucket (std::span< T > span, S &&storage)
	Construct a bucket referencing a `span` and holding `storage`.
constexpr auto	at (size_type pos) -> reference
	Return an element with bounds checking.
constexpr auto	at (size_type pos) const -> const_reference
	Return an element with bounds checking.
constexpr auto	back () -> reference
	Return the last element.
constexpr auto	back () const -> const_reference
	Return the last element.
constexpr auto	begin () const noexcept -> const_iterator
	Return an iterator to the beginning.
constexpr auto	begin () noexcept -> iterator
	Return an iterator to the beginning.
constexpr auto	cbegin () const noexcept -> const_iterator
	Return an iterator to the beginning.
constexpr auto	cend () const noexcept -> const_iterator
	Return an iterator to the end.
template<typename S>
auto	check_storage_type () const noexcept -> bool
	Check if the underlying storage is of a given type.
constexpr auto	crbegin () const noexcept -> const_reverse_iterator
	Return a reverse iterator to the beginning.
constexpr auto	crend () const noexcept -> const_reverse_iterator
	Return a reverse iterator to the end.
constexpr auto	data () const noexcept -> const_pointer
	Return the address of the data.
constexpr auto	data () noexcept -> pointer
	Return the address of the data.
constexpr auto	empty () const noexcept -> bool
	Return whether this bucket is empty.
constexpr auto	end () const noexcept -> const_iterator
	Return an iterator to the end.
constexpr auto	end () noexcept -> iterator
	Return an iterator to the end.
template<typename S>
auto	extract_storage () -> S
	Extract the underlying storage.
constexpr auto	first (size_type count) -> std::span< T >
	Return the span of the first `count` elements.
constexpr auto	first (size_type count) const -> std::span< T const >
	Return the span of the first `count` elements.
constexpr auto	front () -> reference
	Return the first element.
constexpr auto	front () const -> const_reference
	Return the first element.
constexpr auto	last (size_type count) -> std::span< T >
	Return the span of the last `count` elements.
constexpr auto	last (size_type count) const -> std::span< T const >
	Return the span of the last `count` elements.
auto	operator= (bucket &&other) noexcept -> bucket &=default
	Move assignment operator.
auto	operator= (bucket const &other) -> bucket &
	Copy assignment operator (allocates new private storage).
constexpr auto	operator[] (size_type idx) -> reference
	Return an element without bounds checking.
constexpr auto	operator[] (size_type idx) const -> const_reference
	Return an element without bounds checking.
constexpr auto	rbegin () const noexcept -> const_reverse_iterator
	Return a reverse iterator to the beginning.
constexpr auto	rbegin () noexcept -> reverse_iterator
	Return a reverse iterator to the beginning.
constexpr auto	rend () const noexcept -> const_reverse_iterator
	Return a reverse iterator to the end.
constexpr auto	rend () noexcept -> reverse_iterator
	Return a reverse iterator to the end.
void	shrink (std::size_t start, std::size_t count=std::dynamic_extent)
	Shrink the span of the bucket data.
constexpr auto	size () const noexcept -> size_type
	Return the number of data elements in this bucket.
constexpr auto	size_bytes () const noexcept -> size_type
	Return the size of this bucket's data in bytes.
template<typename S>
auto	storage () const -> S const &
	Observe the underlying storage.
constexpr auto	subspan (size_type offset, size_type count=std::dynamic_extent) -> std::span< T >
	Return the span of the given range of elements.
constexpr auto	subspan (size_type offset, size_type count=std::dynamic_extent) const -> std::span< T const >
	Return the span of the given range of elements.

Friends
auto	operator<< (std::ostream &stream, bucket const &bkt) -> std::ostream &
	Stream insertion operator.
constexpr auto	operator== (bucket const &lhs, bucket const &rhs) -> bool
	Equality comparison operator.

Member Typedef Documentation

◆ const_reverse_iterator

template<typename T>

using tcspc::bucket< T >::const_reverse_iterator

Initial value:

typename std::span<T const>::reverse_iterator

Const reverse iterator type.

Constructor & Destructor Documentation

◆ bucket()

template<typename T>

template<typename S>

tcspc::bucket< T >::bucket	(	std::span< T >	span,
		S &&	storage )

inlineexplicit

Construct a bucket referencing a span and holding storage.

This constructor is normally used by bucket sources.

Template Parameters

S	storage type (deduced)

Member Function Documentation

◆ check_storage_type()

template<typename T>

template<typename S>

auto tcspc::bucket< T >::check_storage_type ( ) const -> bool

inlinenodiscardnoexcept

Check if the underlying storage is of a given type.

Template Parameters

S	the storage type to check for

Returns: true if this bucket's storage is of type S

◆ extract_storage()

template<typename T>

template<typename S>

auto tcspc::bucket< T >::extract_storage ( ) -> S

inlinenodiscard

Extract the underlying storage.

The instance becomes an empty bucket after extraction. A bucket obtained from a bucket source (that supports extraction) is required; extracting the storage from a sub-bucket or a copied bucket is not supported (cannot be done because the storage is a private type).

Template Parameters

S	the storage type

Returns: the storage object

Exceptions

std::bad_cast if S does not match the storage type of this bucket

◆ shrink()

template<typename T>

void tcspc::bucket< T >::shrink	(	std::size_t	start,
		std::size_t	count = std::dynamic_extent )

inline

Shrink the span of the bucket data.

Mutates this bucket in place so that its span becomes a subspan of its current span. There is no effect on the storage.

Once shrunk, the excluded part of the data is no longer accessible (except via a sub-bucket, byte bucket, or const bucket previously created from this bucket).

◆ storage()

template<typename T>

template<typename S>

auto tcspc::bucket< T >::storage ( ) const -> S const &

inlinenodiscard

Observe the underlying storage.

Template Parameters

S	the storage type

Returns: const reference to the storage object

Exceptions

std::bad_cast if S does not match the storage type of this bucket

◆ operator==

template<typename T>

auto operator==	(	bucket< T > const &	lhs,
		bucket< T > const &	rhs ) -> bool

friend

Equality comparison operator.

Returns: true if the two buckets contain equal data.

The documentation for this class was generated from the following file:

libtcspc/bucket.hpp

Description

Public Types

Public Member Functions

Friends

Member Typedef Documentation

◆ const_reverse_iterator

Constructor & Destructor Documentation

◆ bucket()

Member Function Documentation

◆ check_storage_type()

◆ extract_storage()

◆ shrink()

◆ storage()

Friends And Related Symbol Documentation

◆ operator==