Slave

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

typedef std::shared_ptr<rogue::interfaces::stream::Slave> rogue::interfaces::stream::SlavePtr

Shared pointer alias for Slave.

The class description is shown below:

class Slave : public rogue::interfaces::stream::Pool, public rogue::EnableSharedFromThis<rogue::interfaces::stream::Slave>

Stream slave endpoint and default frame pool.

A Slave receives frames from upstream masters via acceptFrame() and also implements Pool, so it can service frame-allocation requests in the same stream path. A single slave can be attached to multiple masters.

Slave is not abstract (no pure virtual methods), but it is intended to be subclassed for most real applications (protocol endpoints, transforms, sinks, file/network bridges).

Subclass contract in practice:

  • Primary override point: acceptFrame(). Implement per-frame ingress logic here (decode, transform, queue, forward, or consume).

  • Optional lifecycle override: stop(). Override when the subclass owns worker threads, timers, sockets, or device resources needing clean shutdown.

  • Optional allocation overrides (from Pool): acceptReq() and retBuffer() when custom memory allocation/recycling is needed (for example DMA-backed buffers).

Base-class behavior notes:

  • Base acceptFrame() increments frame/byte counters and can emit debug logging (setDebug()), while taking a frame lock during inspection.

  • If a subclass overrides acceptFrame() and still wants those counters/debug semantics, it should explicitly call Slave::acceptFrame(frame) or provide equivalent logic.

Subclassed by rogue::hardware::axi::AxiStreamDma, rogue::interfaces::stream::Fifo, rogue::interfaces::stream::Filter, rogue::interfaces::stream::RateDrop, rogue::interfaces::stream::SlaveWrap, rogue::interfaces::stream::TcpCore, rogue::protocols::batcher::InverterV1, rogue::protocols::batcher::InverterV2, rogue::protocols::batcher::SplitterV1, rogue::protocols::batcher::SplitterV2, rogue::protocols::packetizer::Application, rogue::protocols::packetizer::Transport, rogue::protocols::rssi::Application, rogue::protocols::rssi::Transport, rogue::protocols::srp::SrpV0, rogue::protocols::srp::SrpV3, rogue::protocols::udp::Client, rogue::protocols::udp::Server, rogue::protocols::xilinx::Xvc, rogue::utilities::Prbs, rogue::utilities::StreamUnZip, rogue::utilities::StreamZip, rogue::utilities::fileio::StreamWriterChannel

Public Functions

Slave()

Constructs a stream slave.

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

virtual ~Slave()

Destroys the stream slave.

virtual void stop()

Shuts down threads associated with this object.

Called during shutdown to stop activity and allow clean process exit. Subclasses should override when they own worker threads or timers.

Exposed as stop() in Python.

void setDebug(uint32_t debug, std::string name)

Sets debug message verbosity and logger name.

This method enables debug messages when using the base Slave class attached as a primary or secondary Slave on a Master. Typically used when attaching a base Slave object for debug purposes.

Exposed as setDebug() in Python.

Parameters:

  • debug – Maximum number of bytes to print in debug message.

  • name – Name included in debug messages.

virtual void acceptFrame(std::shared_ptr<rogue::interfaces::stream::Frame> frame)

Accepts a frame from a master.

This method is called by the Master object to which this Slave is attached when passing a Frame. By default this method will print debug information if enabled and is typically re-implemented by a Slave sub-class. This is the primary subclass extension point for implementing stream processing behavior.

Base implementation behavior:

Re-implemented as _acceptFrame() in Python subclasses.

Parameters:

frame – Frame pointer (FramePtr).

uint64_t getFrameCount()

Returns frame counter.

Returns the total frames received. Only valid if acceptFrame is not re-implemented as a sub-class. Typically used when attaching a base Slave object for debug purposes.

Exposed as getFrameCount() in Python.

Returns:

Total number of Frame objects received.

uint64_t getByteCount()

Returns byte counter.

Returns the total bytes received. Only valid if acceptFrame is not re-implemented as a sub-class. Typically used when attaching a base Slave object for debug purposes.

Exposed as getByteCount() in Python.

Returns:

Total number of bytes received.

bool ensureSingleBuffer(std::shared_ptr<rogue::interfaces::stream::Frame> &frame, bool reqEn)

Ensures frame is backed by a single buffer.

This method makes sure the passed frame is composed of a single buffer. If the reqEn flag is true and the passed frame is not single-buffer, a new frame can be requested and data copied into it, updating the passed frame pointer. A frame lock must be held when this method is called.

Not exposed to Python.

Parameters:

  • frame – Reference to frame pointer (FramePtr).

  • reqEn – Flag to determine if a new frame should be requested.

Returns:

true if frame is single-buffer after processing.

std::shared_ptr<rogue::interfaces::stream::Frame> reqLocalFrame(uint32_t size, bool zeroCopyEn)

Services a local frame allocation request through this object’s pool interface.

This bypasses upstream links and allocates from the local Pool implementation.

Parameters:

  • size – Minimum required frame payload size in bytes.

  • zeroCopyEn – True to allow zero-copy buffer use when supported.

Returns:

Newly allocated frame pointer.

boost::python::object lshiftPy(boost::python::object p)

Supports << operator usage from Python.

Parameters:

p – Python object expected to resolve to a stream Master.

Returns:

Original Python object for chaining semantics.

std::shared_ptr<rogue::interfaces::stream::Master> &operator<<(std::shared_ptr<rogue::interfaces::stream::Master> &other)

Connects this slave to a master via stream chaining operator.

Parameters:

other – Upstream master to attach.

Returns:

Reference to other for chaining.

Public Static Functions

static std::shared_ptr<rogue::interfaces::stream::Slave> create()

Creates a new stream slave.

Exposed as rogue.interfaces.stream.Slave() in Python. 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 a newly created slave.

static void setup_python()

Registers this type with Python bindings.