Frame and buffer allocator for stream endpoints. More...

#include <Pool.h>

Inheritance diagram for rogue::interfaces::stream::Pool:

Public Member Functions
	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.

Static Public Member Functions
static void	setup_python ()
	Registers this type with Python bindings.

Protected Member Functions
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

Frame and buffer allocator for stream endpoints.

Pool is the stream-memory allocation layer used by Slave objects to service frame requests from upstream Master objects (Master::reqFrame() eventually resolves through Pool::acceptReq() on the primary slave).

Core responsibilities:

Allocate and construct Frame objects.
Allocate and construct the underlying Buffer objects used by each frame.
Reclaim and optionally recycle buffer data when buffers are returned.
Track allocation statistics (getAllocBytes(), getAllocCount()).

Default behavior:

A request typically returns a frame with one buffer sized for the request.
Buffer memory is released when returned (no caching required).

Fixed-size mode (setFixedSize()):

Each allocated buffer uses the configured fixed buffer size.
If a frame request is larger than one fixed buffer, the frame is built from multiple buffers so total capacity satisfies the request.

Pooling mode (setPoolSize() with fixed-size operation):

Returned buffer memory blocks are cached in an internal free queue for reuse.
Pool size defines the maximum number of cached entries retained.
Reuse reduces allocator churn for high-rate streaming workloads.

Subclassing/advanced use:

Override acceptReq() to customize how frames are assembled.
Override retBuffer() to customize return/recycle behavior.
Use protected helpers (allocBuffer(), createBuffer(), decCounter()) when integrating external memory providers, such as DMA-backed memory.

Definition at line 71 of file Pool.h.

Constructor & Destructor Documentation

◆ Pool()

rogue::interfaces::stream::Pool::Pool ( )

Constructs a pool with default allocation behavior enabled.

Creator.

Company : SLAC National Accelerator Laboratory

Description: Stream memory pool 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 42 of file Pool.cpp.

◆ ~Pool()

rogue::interfaces::stream::Pool::~Pool ( )

virtual

Destroys the pool and releases any cached buffer storage.

Destructor.

Definition at line 51 of file Pool.cpp.

Member Function Documentation

◆ acceptReq()

rogue::interfaces::stream::FramePtr rogue::interfaces::stream::Pool::acceptReq	(	uint32_t	size,
		bool	zeroCopyEn
	)

virtual

Services a frame allocation request from a master.

Accept a frame request. Called from master.

Called by Master::reqFrame() to allocate a frame and one or more buffers.

Parameters

size	Minimum requested payload size in bytes.
zeroCopyEn	True to allow zero-copy buffers when supported.

Returns: Newly allocated frame.

Reimplemented in rogue::hardware::axi::AxiStreamDma, rogue::protocols::packetizer::Application, rogue::protocols::rssi::Application, rogue::utilities::StreamUnZip, and rogue::utilities::StreamZip.

Definition at line 72 of file Pool.cpp.

◆ allocBuffer()

rogue::interfaces::stream::BufferPtr rogue::interfaces::stream::Pool::allocBuffer	(	uint32_t	size,
		uint32_t *	total
	)

protected

Allocate a buffer passed size.

Allocate and Create a Buffer This method is the default Buffer allocator. The requested buffer is created from either a malloc call or fulling a free entry from the memory pool if it is enabled. If fixed size is configured the size parameter is ignored and a Buffer is returned with the fixed size amount of memory. The passed total value is incremented by the allocated Buffer size. This method is protected to allow it to be called by a sub-class of Pool.

Not exposed to Python

Parameters

size	Buffer size requested
total	Pointer to current total size

Returns: Allocated Buffer pointer as BufferPtr

Definition at line 142 of file Pool.cpp.

◆ createBuffer()

rogue::interfaces::stream::BufferPtr rogue::interfaces::stream::Pool::createBuffer	(	void *	data,
		uint32_t	meta,
		uint32_t	size,
		uint32_t	alloc
	)

protected

Creates a Buffer with a pre-allocated data block.

Create a Buffer with passed data.

This method is used to create a Buffer with a pre-allocated block of memory. This can be used when the block of memory is allocated by a hardware DMA driver. This method is protected to allow it to be called by a sub-class of Pool.

Not exposed to Python

Parameters

data	Data pointer to pre-allocated memory block
meta	Meta data associated with pre-allocated memory block
size	Usable size of memory block (may be smaller than allocated size)
alloc	Allocated size of memory block (may be greater than requested size)

Returns: Allocated Buffer pointer as BufferPtr

Definition at line 178 of file Pool.cpp.

◆ decCounter()

void rogue::interfaces::stream::Pool::decCounter ( uint32_t alloc )

protected

Decrements allocation counter.

Track buffer deletion.

Called in a sub-class to decrement the allocated byte count

Not exposed to Python

Parameters

alloc Amount of memory be de-allocated.

Definition at line 192 of file Pool.cpp.

◆ getAllocBytes()

uint32_t rogue::interfaces::stream::Pool::getAllocBytes ( )

Returns total currently allocated bytes.

Get allocated memory.

This value is incremented as buffers are allocated and decremented as buffers are freed.

Exposed as getAllocBytes() in Python.

Returns: Total currently allocated bytes.

Definition at line 58 of file Pool.cpp.

◆ getAllocCount()

uint32_t rogue::interfaces::stream::Pool::getAllocCount ( )

Returns total currently allocated buffer count.

Get allocated count.

This value is incremented as buffers are allocated and decremented as buffers are freed.

Exposed as getAllocCount() in Python.

Returns: Total currently allocated buffers.

Definition at line 63 of file Pool.cpp.

◆ getFixedSize()

uint32_t rogue::interfaces::stream::Pool::getFixedSize ( )

Returns fixed-size allocation setting.

Get fixed size mode.

A return value of 0 means fixed-size mode is disabled.

Exposed as getFixedSize() in Python.

Returns: Fixed size value or 0 when fixed-size mode is disabled.

Definition at line 123 of file Pool.cpp.

◆ getPoolSize()

uint32_t rogue::interfaces::stream::Pool::getPoolSize ( )

Returns configured maximum number of cached pool entries.

Get pool size.

Exposed as getPoolSize() in Python.

Returns: Pool size.

Definition at line 136 of file Pool.cpp.

◆ retBuffer()

void rogue::interfaces::stream::Pool::retBuffer	(	uint8_t *	data,
		uint32_t	meta,
		uint32_t	size
	)

virtual

Returns buffer data to the allocator.

Return a buffer.

This method is called by the Buffer destructor in order to free the associated Buffer memory. May be overridden by a subclass to change the way the buffer data is returned.

Parameters

data	Data pointer to release.
meta	Metadata specific to the allocator.
size	Size of data buffer.

Reimplemented in rogue::hardware::axi::AxiStreamDma.

Definition at line 88 of file Pool.cpp.

◆ setFixedSize()

void rogue::interfaces::stream::Pool::setFixedSize ( uint32_t size )

Sets fixed-size mode.

Set fixed size mode.

This method puts the allocator into fixed size mode.

Exposed as setFixedSize() in Python.

Parameters

size	Fixed size value.

Definition at line 115 of file Pool.cpp.

◆ setPoolSize()

void rogue::interfaces::stream::Pool::setPoolSize ( uint32_t size )

Sets buffer pool size.

Set buffer pool size.

Exposed as setPoolSize() in Python.

Parameters

size	Number of entries to keep in the pool.

Definition at line 128 of file Pool.cpp.

◆ setup_python()

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

static

Registers this type with Python bindings.

Definition at line 102 of file Pool.cpp.

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Pool()

Company : SLAC National Accelerator Laboratory

need to be reworked.

contained in the LICENSE.txt file.

◆ ~Pool()

Member Function Documentation

◆ acceptReq()

◆ allocBuffer()

◆ createBuffer()

◆ decCounter()

◆ getAllocBytes()

◆ getAllocCount()

◆ getFixedSize()

◆ getPoolSize()

◆ retBuffer()

◆ setFixedSize()

◆ setPoolSize()

◆ setup_python()