Master

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

typedef std::shared_ptr<rogue::interfaces::stream::Master> rogue::interfaces::stream::MasterPtr

Shared pointer alias for Master.

The class description is shown below:

class Master : public rogue::EnableSharedFromThis<rogue::interfaces::stream::Master>

Stream master endpoint.

Source object for sending frames to one or more stream slaves. The first attached slave is used to allocate new frames and is the last to receive sent frames.

Master is not an abstract class (no pure virtual methods), but it is commonly used as a base for protocol/source implementations.

Subclass expectations in practice:

  • No Master method is required to be overridden.

  • Most subclasses keep addSlave(), reqFrame(), and sendFrame() as-is and call reqFrame()/sendFrame() from their own public APIs or worker threads (for example protocol transmit paths and file readers).

  • stop() is the primary Master method intended for override when the subclass owns worker threads, timers, sockets, or device handles.

  • For transform/bridge classes that are both source and sink, ingress logic is usually implemented by also inheriting Slave and overriding Slave::acceptFrame(), while egress uses this Master interface.

Subclassed by rogue::hardware::axi::AxiStreamDma, rogue::interfaces::stream::Fifo, rogue::interfaces::stream::Filter, rogue::interfaces::stream::RateDrop, 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::Cmd, 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::StreamReader

Public Functions

Master()

Constructs a stream master.

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

virtual ~Master()

Destroys the stream master.

uint32_t slaveCount()

Returns the number of attached slaves.

Exposed as _slaveCount() in Python.

Returns:

Number of attached slaves.

void addSlave(std::shared_ptr<rogue::interfaces::stream::Slave> slave)

Attaches a downstream slave.

Multiple slaves are supported. The first attached slave is used for frame allocation and receives frames last during send. Exposed as _addSlave() in Python.

Parameters:

slave – Stream slave pointer.

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

Requests allocation of a new frame from the primary slave.

Creates an empty frame with at least the requested payload capacity. The Master will forward this request to the primary Slave object. The request for a new Frame includes a flag which indicates if a zeroCopy frame is allowed. In most cases this flag can be set to true. Non-zero-copy frames are requested if the Master may need to transmit the same frame multiple times. Exposed as _reqFrame() in Python.

Parameters:

  • size – Minimum requested payload size in bytes.

  • zeroCopyEn – Set to true when zero-copy frame allocation is allowed.

Returns:

Newly allocated frame pointer.

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

Sends a frame to all attached slaves.

This method sends the passed Frame to all of the attached Slave objects by calling their acceptFrame() method. First the secondary Slaves are called in order of attachment, followed last by the primary Slave. If the Frame is a zero copy frame it will most likely be empty when the sendFrame() method returns

Exposed as _sendFrame() in Python.

Parameters:

frame – Frame to send.

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

Ensures a frame is represented by a single buffer.

If the reqEn flag is true and the passed frame is not a single buffer, a new frame will be requested and the frame data will be copied, with the passed frame pointer being updated. The return value will indicate if the frame is a single buffer at the end of the process. A frame lock must be held when this method is called.

Not exposed to Python.

Parameters:

  • frame – Reference to frame pointer.

  • reqEn – Set to true to allow allocating and copying into a new frame.

Returns:

true if the resulting frame is single-buffer.

virtual void stop()

Stops frame generation and shuts down associated threads.

Exposed as stop() in Python.

This is the primary subclass hook on Master. Override when the subclass owns background activity or transport resources that require deterministic shutdown.

void equalsPy(boost::python::object p)

Supports == operator usage from Python.

Parameters:

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

boost::python::object rshiftPy(boost::python::object p)

Supports >> operator usage from Python.

Parameters:

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

Returns:

Original Python object for chaining semantics.

void operator==(std::shared_ptr<rogue::interfaces::stream::Slave> &other)

Supports == operator usage in C++.

Parameters:

other – Downstream slave to attach.

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

Connects this master to a slave via stream chaining operator.

Parameters:

other – Downstream slave to attach.

Returns:

Reference to other for chaining.

Public Static Functions

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

Creates a stream master.

Exposed as rogue.interfaces.stream.Master() 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 the created master.

static void setup_python()

Registers this type with Python bindings.