libtcspc.PyBucketSource

class libtcspc.PyBucketSource

Bases: ABC

Bucket source implemented in Python and supplied as an argument upon creation of the execution context.

A PyBucketSource provides the storage that backs the buckets emitted by processors such as Acquire, Batch, BatchFromBytes, and ReadBinaryStream. It is bound to a graph by passing a Param as the buffer_provider argument of such a processor, and the concrete instance is supplied to the ExecutionContext at execution time.

When a bucket whose storage came from a PyBucketSource flows unmodified to a PySink, the sink receives a NumPy array that is a zero-copy view of the buffer originally returned by bucket_of_size, trimmed to the bucket’s valid length. The buffer is kept alive for as long as the bucket (or the sink’s view of it) exists.

A PyBucketSource supports shared views and may be used with processors that require a sharable bucket source. A read-only shared view delivered to a PySink is likewise zero-copy: a read-only NumPy array co-owning the same buffer.

See also

BucketSource

Built-in C++-side bucket sources.

abstractmethod bucket_of_size(size)

Return a buffer to back a bucket of at least size elements.

Parameters:

size (int) – The minimum number of elements the returned buffer must hold.

Returns:

A buffer-protocol object (typically a NumPy array) of length at least size whose dtype matches the element type of the buckets requested by the processor. The bucket will use the first size elements as its storage.

Return type:

Any

Notes

An implementation must not retain or reuse a buffer it has already returned while the corresponding bucket, or any shared view derived from it, may still be in flight; doing so corrupts data still being processed.