libtcspc.AcquireFullBuckets¶

final class libtcspc.AcquireFullBuckets(event_type, reader, buffer_provider, batch_size, access_tag)[source]¶

Bases: Node

Source processor that acquires data into fixed-size buckets while also delivering real-time read-only views.

Like Acquire, this plugs a pull-based data source into a libtcspc processing graph: on each iteration the processor obtains an empty bucket from the buffer provider, calls the reader to fill it, and collects the data into fixed-size buckets. Unlike Acquire, it has two outputs:

live: a read-only ConstBucketEvent view of the data read on each individual read, delivered immediately (typically used for live display).
batch: a full BucketEvent bucket emitted whenever batch_size elements have been collected, plus any partial final bucket on flush (typically used for saving to disk).

The live views are zero-copy when the buffer provider supplies shared-view-capable buckets, so they must not be modified.

The acquisition runs until the reader signals end of stream (by returning None), the reader raises an exception, or the acquisition is halted via the AcquireAccessor retrieved from the ExecutionContext using access_tag. Halting is asynchronous: the halt() call returns immediately, but the acquisition may continue briefly. Wait for graph execution to finish before tearing down resources used by the reader.

Parameters:

event_type (EventType) – Element type of the acquired data (typically a byte or integer type). Each emitted bucket holds a contiguous array of this type.
reader (AcquisitionReader or Param[PyAcquisitionReader]) – Object that fills supplied buffers with acquired data on each call. Pass an AcquisitionReader instance (such as NullReader) to use a built-in C++-side reader, or wrap a Python callable in a runtime Param of type PyAcquisitionReader to bind it at execution time.
buffer_provider (BucketSource or Param[PyBucketSource] or None) – Source of buckets used to hold each batch. If None, a default RecyclingBucketSource for event_type is used. A runtime Param of type PyBucketSource binds a Python bucket source at execution time. The buffer provider must support shared views unless the live output is connected to a SinkAll.
batch_size (int or Param[int] or None) – Number of elements collected in each full bucket. Smaller values reduce latency; larger values reduce per-read overhead. Defaults to 65536. Must be positive.
access_tag (AccessTag) – Tag used to retrieve an AcquireAccessor (which provides halt()) from the ExecutionContext at runtime.

Notes

Events handled:

This processor has no input events; it is a source.
Emits ConstBucketEvent of event_type on the live output for each non-empty read, and BucketEvent of event_type on the batch output whenever a full bucket is collected.
End of input is initiated when the reader returns None, whereupon both downstreams are flushed (any partial bucket is emitted on batch first). If halted via AcquireAccessor before end of stream, the downstreams are not flushed and a halt exception is raised.