libtcspc.ReadBinaryStream¶

final class libtcspc.ReadBinaryStream(event_type, stream, max_length=None, buffer_provider=None, read_granularity_bytes=65536)[source]¶

Bases: Node

Source processor that reads events from a binary input stream.

The stream must contain a contiguous array of event_type, which must be a trivially-typed event. Events are read from the stream in batches and placed into buckets obtained from the buffer provider. Each completed read is emitted as a BucketEvent of event_type. The read size is governed by read_granularity_bytes and by the size of event_type. The first read may be shortened to align subsequent read offsets to the granularity, and the last read may be shortened to avoid exceeding max_length.

Parameters:

event_type (EventType) – Element type stored in the stream. Must be a trivially-typed event.
stream (InputStream) – The input stream to read from (for example a BinaryFileInputStream).
max_length (int or Param[int] or None) – Maximum number of bytes to read. None (the default) means read to end of stream. Should be a multiple of the size of event_type for clean truncation.
buffer_provider (BucketSource or None) – Source of buckets used to hold each read. If None, a default RecyclingBucketSource for event_type is used. Must be able to circulate at least 2 buckets without blocking.
read_granularity_bytes (int or Param[int]) – Minimum read size in bytes. Defaults to 65536. Larger reads have less per-byte overhead but may pollute CPU caches; try different powers of two and measure.

Notes

Events handled:

This processor has no input events; it is a source.
Emits BucketEvent of event_type for each completed read.
End of input: pass through. Raises an exception (corresponding to C++ input_output_error) on a stream read error; emits a WarningEvent if the stream ends with fewer than sizeof(event_type) bytes remaining.