Stream master endpoint. More...

#include <Master.h>

Inheritance diagram for rogue::interfaces::stream::Master:

Public Member Functions
	Master ()
	Constructs a stream master.

virtual	~Master ()
	Destroys the stream master.

uint32_t	slaveCount ()
	Returns the number of attached slaves.

void	addSlave (std::shared_ptr< rogue::interfaces::stream::Slave > slave)
	Attaches a downstream slave.

std::shared_ptr< rogue::interfaces::stream::Frame >	reqFrame (uint32_t size, bool zeroCopyEn)
	Requests allocation of a new frame from the primary slave.

void	sendFrame (std::shared_ptr< rogue::interfaces::stream::Frame > frame)
	Sends a frame to all attached slaves.

bool	ensureSingleBuffer (std::shared_ptr< rogue::interfaces::stream::Frame > &frame, bool reqEn)
	Ensures a frame is represented by a single buffer.

virtual void	stop ()
	Stops frame generation and shuts down associated threads.

void	equalsPy (boost::python::object p)
	Supports `==` operator usage from Python.

boost::python::object	rshiftPy (boost::python::object p)
	Supports `>>` operator usage from Python.

void	operator== (std::shared_ptr< rogue::interfaces::stream::Slave > &other)
	Supports `==` operator usage in C++.

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.

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::stream::Master >
std::shared_ptr< rogue::interfaces::stream::Master >	shared_from_this ()
	Returns a `shared_ptr<T>` for this instance.

Public Member Functions inherited from rogue::EnableSharedFromThisBase
virtual	~EnableSharedFromThisBase ()
	Virtual destructor for polymorphic base usage.

Static Public Member Functions
static std::shared_ptr< rogue::interfaces::stream::Master >	create ()
	Creates a stream master.

static void	setup_python ()
	Registers this type with Python bindings.

Detailed Description

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.

Definition at line 65 of file Master.h.

Constructor & Destructor Documentation

◆ Master()

rogue::interfaces::stream::Master::Master ( )

Constructs a stream master.

Creator.

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

Definition at line 46 of file Master.cpp.

◆ ~Master()

rogue::interfaces::stream::Master::~Master ( )

virtual

Destroys the stream master.

Destructor.

Definition at line 51 of file Master.cpp.

Member Function Documentation

◆ addSlave()

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

Attaches a downstream slave.

Add 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.

Definition at line 59 of file Master.cpp.

◆ create()

rogue::interfaces::stream::MasterPtr rogue::interfaces::stream::Master::create ( )

static

Creates a stream master.

Class creation.

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.

Company : SLAC National Accelerator Laboratory

Description:

Stream interface master

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.

Definition at line 40 of file Master.cpp.

◆ ensureSingleBuffer()

bool rogue::interfaces::stream::Master::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.

Definition at line 91 of file Master.cpp.

◆ equalsPy()

void rogue::interfaces::stream::Master::equalsPy ( boost::python::object p )

Supports == operator usage from Python.

Parameters

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

Definition at line 138 of file Master.cpp.

◆ operator==()

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

Supports == operator usage in C++.

Support == operator in C++.

Parameters

other Downstream slave to attach.

Definition at line 224 of file Master.cpp.

◆ operator>>()

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

Connects this master to a slave via stream chaining operator.

Support >> operator in C++.

Parameters

other Downstream slave to attach.

Returns: Reference to other for chaining.

Definition at line 243 of file Master.cpp.

◆ reqFrame()

rogue::interfaces::stream::FramePtr rogue::interfaces::stream::Master::reqFrame	(	uint32_t	size,
		bool	zeroCopyEn
	)

Requests allocation of a new frame from the primary slave.

Request frame from 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.

Definition at line 66 of file Master.cpp.

◆ rshiftPy()

boost::python::object rogue::interfaces::stream::Master::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.

Definition at line 191 of file Master.cpp.

◆ sendFrame()

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

Sends a frame to all attached slaves.

Push frame to 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.

Definition at line 77 of file Master.cpp.

◆ setup_python()

void rogue::interfaces::stream::Master::setup_python ( )

static

Registers this type with Python bindings.

Definition at line 121 of file Master.cpp.

◆ slaveCount()

uint32_t rogue::interfaces::stream::Master::slaveCount ( )

Returns the number of attached slaves.

Exposed as _slaveCount() in Python.

Returns: Number of attached slaves.

Definition at line 54 of file Master.cpp.

◆ stop()

void rogue::interfaces::stream::Master::stop ( )

virtual

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.

Reimplemented in rogue::hardware::axi::AxiStreamDma, rogue::interfaces::stream::TcpCore, rogue::protocols::udp::Client, rogue::protocols::udp::Server, and rogue::protocols::xilinx::Xvc.

Definition at line 119 of file Master.cpp.

The documentation for this class was generated from the following files:

/home/runner/work/rogue/rogue/include/rogue/interfaces/stream/Master.h
/home/runner/work/rogue/rogue/src/rogue/interfaces/stream/Master.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Master()

◆ ~Master()

Member Function Documentation

◆ addSlave()

◆ create()

Company : SLAC National Accelerator Laboratory

Stream interface master

contained in the LICENSE.txt file.

◆ ensureSingleBuffer()

◆ equalsPy()

◆ operator==()

◆ operator>>()

◆ reqFrame()

◆ rshiftPy()

◆ sendFrame()

◆ setup_python()

◆ slaveCount()

◆ stop()