StreamWriter

The StreamWriter class writes Rogue stream frames to disk. It can accept frames from multiple incoming sources, with StreamWriterChannel providing the per-channel input interfaces. This class can be sub-classed to support custom formats by overriding writeFile().

The shared on-disk record format (headers and metadata field encoding) is documented here:

• Rogue File Data Format

Raw Mode

When setRaw(True) is enabled, StreamWriter writes only payload bytes for each frame and omits per-record headers. In this mode, channel/error/flags metadata is not persisted.

File Splitting Behavior

If setMaxSize() is non-zero, StreamWriter rolls to a new output file before writing a record that would exceed the configured limit.

Split files use incrementing numeric suffixes:

myFile.dat.1
myFile.dat.2
myFile.dat.3

StreamWriter objects in C++ are referenced by the following shared pointer typedef:

typedef std::shared_ptr<rogue::utilities::fileio::StreamWriter> rogue::utilities::fileio::StreamWriterPtr

The class description is shown below:

class StreamWriter : public rogue::EnableSharedFromThis<rogue::utilities::fileio::StreamWriter>

Coordinates channelized frame capture into Rogue stream data files.

StreamWriter accepts frames through StreamWriterChannel instances and serializes them into a shared output file (or indexed file set when setMaxSize() is enabled).

Default banked format:

• 32-bit length word (bank payload length in bytes).

• 32-bit header word: channel, frame error, and frame flags.

• Raw frame payload bytes.

Raw mode (setRaw(true)) bypasses bank headers and writes only payload bytes. This is useful for tools that expect a byte stream without Rogue framing metadata.

Public Functions

StreamWriter()

Constructs a stream writer.

This constructor is a low-level C++ allocation path. Prefer create() when shared ownership or Python exposure is required.

virtual ~StreamWriter()

Destroys the stream writer and closes open resources.

void open(std::string file)

Opens a data file.

Resets counters and bandwidth history. If a max size is configured, the first opened file is <file>.1 and rollover continues with .2, .3, etc.

Parameters:

file – Output file path.

void close()

Closes the currently open data file.

bool isOpen()

Returns whether a data file is open.

Returns:

True if a file is open.

void setRaw(bool raw)

Sets raw output mode.

• false (default): write banked Rogue format with length/header words.

• true: write frame payload bytes only.

Parameters:

raw – True to write raw frame payload only.

bool getRaw()

Gets raw output mode state.

Returns:

True when raw output mode is enabled.

void setBufferSize(uint32_t size)

Sets write buffering size.

Changing size flushes pending data and reallocates internal buffer. A value of 0 disables staging and writes directly to the file.

Parameters:

size – Buffer size in bytes, 0 disables buffering.

void setMaxSize(uint64_t size)

Sets automatic file rollover size.

When non-zero, writes are split into indexed files (.1, .2, …), and rollover occurs before a write that would exceed the limit.

Parameters:

size – Maximum file size in bytes, 0 for unlimited.

void setDropErrors(bool drop)

Configures whether errored frames are dropped.

When enabled, frames with non-zero frame->getError() are skipped.

Parameters:

drop – True to drop errored frames instead of writing them.

std::shared_ptr<rogue::utilities::fileio::StreamWriterChannel> getChannel(uint8_t channel)

Gets or creates a channel writer endpoint.

The returned StreamWriterChannel is a stream::Slave that routes frames into this writer with the specified channel ID.

Parameters:

channel – Channel ID.

Returns:

Channel writer object bound to channel.

uint64_t getTotalSize()

Returns cumulative bytes written across all files.

Returns:

Total written bytes.

uint64_t getCurrentSize()

Returns current output file size.

Returns:

Current file size in bytes.

double getBandwidth()

Returns recent write bandwidth estimate.

Returns:

Bandwidth in bytes per second.

uint32_t getFrameCount()

Returns number of frames written to the current file session.

Returns:

Frame count.

bool waitFrameCount(uint32_t count, uint64_t timeout)

Blocks until a target frame count is reached or timeout expires.

Parameters:

• count – Target frame count threshold.

• timeout – Timeout in microseconds. 0 waits indefinitely.

Returns:

True if threshold reached before timeout.

Public Static Functions

static std::shared_ptr<rogue::utilities::fileio::StreamWriter> create()

Creates a stream writer instance.

This static factory is the preferred construction path when the object is shared across Rogue graph connections or exposed to Python. It returns std::shared_ptr ownership compatible with Rogue pointer typedefs.

Returns:

Shared pointer to the created writer.

static void setup_python()

Registers Python bindings for this class.