Stream slave endpoint and default frame pool. More...

#include <Slave.h>

Inheritance diagram for rogue::interfaces::stream::Slave:

Public Member Functions
	Slave ()
	Constructs a stream slave.

virtual	~Slave ()
	Destroys the stream slave.

virtual void	stop ()
	Shuts down threads associated with this object.

void	setDebug (uint32_t debug, std::string name)
	Sets debug message verbosity and logger name.

virtual void	acceptFrame (std::shared_ptr< rogue::interfaces::stream::Frame > frame)
	Accepts a frame from a master.

uint64_t	getFrameCount ()
	Returns frame counter.

uint64_t	getByteCount ()
	Returns byte counter.

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

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.

boost::python::object	lshiftPy (boost::python::object p)
	Supports `<<` operator usage from Python.

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.

Public Member Functions inherited from rogue::interfaces::stream::Pool
	Pool ()
	Constructs a pool with default allocation behavior enabled.

virtual	~Pool ()
	Destroys the pool and releases any cached buffer storage.

uint32_t	getAllocBytes ()
	Returns total currently allocated bytes.

uint32_t	getAllocCount ()
	Returns total currently allocated buffer count.

virtual std::shared_ptr< rogue::interfaces::stream::Frame >	acceptReq (uint32_t size, bool zeroCopyEn)
	Services a frame allocation request from a master.

virtual void	retBuffer (uint8_t *data, uint32_t meta, uint32_t size)
	Returns buffer data to the allocator.

void	setFixedSize (uint32_t size)
	Sets fixed-size mode.

uint32_t	getFixedSize ()
	Returns fixed-size allocation setting.

void	setPoolSize (uint32_t size)
	Sets buffer pool size.

uint32_t	getPoolSize ()
	Returns configured maximum number of cached pool entries.

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::stream::Pool >
std::shared_ptr< rogue::interfaces::stream::Pool >	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.

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

Static Public Member Functions
static std::shared_ptr< rogue::interfaces::stream::Slave >	create ()
	Creates a new stream slave.

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

Static Public Member Functions inherited from rogue::interfaces::stream::Pool
static void	setup_python ()
	Registers this type with Python bindings.

Additional Inherited Members
Protected Member Functions inherited from rogue::interfaces::stream::Pool
std::shared_ptr< rogue::interfaces::stream::Buffer >	allocBuffer (uint32_t size, uint32_t *total)
	Allocate a buffer passed size.

std::shared_ptr< rogue::interfaces::stream::Buffer >	createBuffer (void *data, uint32_t meta, uint32_t size, uint32_t alloc)
	Creates a Buffer with a pre-allocated data block.

void	decCounter (uint32_t alloc)
	Decrements allocation counter.

Detailed Description

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.

Definition at line 71 of file Slave.h.

Constructor & Destructor Documentation

◆ Slave()

rogue::interfaces::stream::Slave::Slave ( )

Constructs a stream slave.

Creator.

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

Definition at line 55 of file Slave.cpp.

◆ ~Slave()

rogue::interfaces::stream::Slave::~Slave ( )

virtual

Destroys the stream slave.

Destructor.

Definition at line 62 of file Slave.cpp.

Member Function Documentation

◆ acceptFrame()

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

virtual

Accepts a frame from a master.

Accept a frame from 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:

Increments getFrameCount() / getByteCount() counters.
Acquires a frame lock and optionally logs data bytes per setDebug().

Re-implemented as _acceptFrame() in Python subclasses.

Parameters

frame Frame pointer (FramePtr).

Reimplemented in 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::fileio::StreamWriterChannel, rogue::utilities::Prbs, rogue::utilities::StreamUnZip, and rogue::utilities::StreamZip.

Definition at line 73 of file Slave.cpp.

◆ create()

rogue::interfaces::stream::SlavePtr rogue::interfaces::stream::Slave::create ( )

static

Creates a new stream slave.

Class creation.

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.

Company : SLAC National Accelerator Laboratory

Description: Stream interface slave The function calls in this are a mess! create buffer, allocate buffer, etc

need to be reworked.

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 49 of file Slave.cpp.

◆ ensureSingleBuffer()

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

Definition at line 144 of file Slave.cpp.

◆ getByteCount()

uint64_t rogue::interfaces::stream::Slave::getByteCount ( )

Returns byte counter.

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

Definition at line 139 of file Slave.cpp.

◆ getFrameCount()

uint64_t rogue::interfaces::stream::Slave::getFrameCount ( )

Returns frame counter.

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

Definition at line 134 of file Slave.cpp.

◆ lshiftPy()

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

Definition at line 201 of file Slave.cpp.

◆ operator<<()

std::shared_ptr< rogue::interfaces::stream::Master > & rogue::interfaces::stream::Slave::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.

◆ reqLocalFrame()

rogue::interfaces::stream::FramePtr rogue::interfaces::stream::Slave::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.

Definition at line 173 of file Slave.cpp.

◆ setDebug()

void rogue::interfaces::stream::Slave::setDebug	(	uint32_t	debug,
		std::string	name
	)

Sets debug message verbosity and logger name.

Set debug message size.

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.

Definition at line 67 of file Slave.cpp.

◆ setup_python()

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

static

Registers this type with Python bindings.

Definition at line 177 of file Slave.cpp.

◆ stop()

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

virtual

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.

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 64 of file Slave.cpp.

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

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

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Slave()

◆ ~Slave()

Member Function Documentation

◆ acceptFrame()

◆ create()

Company : SLAC National Accelerator Laboratory

need to be reworked.

contained in the LICENSE.txt file.

◆ ensureSingleBuffer()

◆ getByteCount()

◆ getFrameCount()

◆ lshiftPy()

◆ operator<<()

◆ reqLocalFrame()

◆ setDebug()

◆ setup_python()

◆ stop()