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:

For conceptual utility usage, see:

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
[header]

The class description is shown below:

class StreamWriter : public rogue::EnableSharedFromThis<rogue::utilities::fileio::StreamWriter>
[header]

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()
[header] [impl]

Constructs a stream writer.

Creator.

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

virtual ~StreamWriter()
[header] [impl]

Destroys the stream writer and closes open resources.

Deconstructor.

void open(std::string file)
[header] [impl]

Opens a data file.

Open 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()
[header] [impl]

Closes the currently open data file.

Close a data file.

bool isOpen()
[header] [impl]

Returns whether a data file is open.

Get open status.

Returns:

True if a file is open.

void setRaw(bool raw)
[header] [impl]

Sets raw output mode.

Set raw 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()
[header] [impl]

Gets raw output mode state.

Get raw mode flag.

Returns:

True when raw output mode is enabled.

void setBufferSize(uint32_t size)
[header] [impl]

Sets write buffering size.

Set buffering size, 0 to disable.

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)
[header] [impl]

Sets automatic file rollover size.

Set max file size, 0 for unlimited.

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)
[header] [impl]

Configures whether errored frames are dropped.

Set drop errors flag.

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)
[header] [impl]

Gets or creates a channel writer endpoint.

Get a slave port.

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()
[header] [impl]

Returns cumulative bytes written across all files.

Get total file size.

Returns:

Total written bytes.

uint64_t getCurrentSize()
[header] [impl]

Returns current output file size.

Get current file size.

Returns:

Current file size in bytes.

double getBandwidth()
[header] [impl]

Returns recent write bandwidth estimate.

Get instantaneous bandwidth in bytes per second over the last second.

Returns:

Bandwidth in bytes per second.

uint32_t getFrameCount()
[header] [impl]

Returns number of frames written to the current file session.

Get current frame count.

Returns:

Frame count.

bool waitFrameCount(uint32_t count, uint64_t timeout)
[header] [impl]

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()
[header] [impl]

Creates a stream writer instance.

Class creation.

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.

Company : SLAC National Accelerator Laboratory

Description : Class to coordinate data file writing. This class supports multiple stream slaves, each with the ability to write to a common data file. The data file is a series of banks. Each bank has a channel and frame flags. The channel is per source and the lower 24 bits of the frame flags are used as the flags. The bank is proceeded by 2 - 32-bit headers to indicate bank information and length:

headerA: [31:0] = Length of data block in bytes headerB 31:24 = Channel ID 23:16 = Frame error 15:0 = Frame flags

This file is part of the rogue software platform. It is subject to the license terms in the LICENSE.txt file found in the top-level directory of this distribution and at: https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html. No part of the rogue software platform, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE.txt file.

Returns:

Shared pointer to the created writer.

static void setup_python()
[header] [impl]

Registers Python bindings for this class.

Setup class in python.