Pool

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

typedef std::shared_ptr<rogue::interfaces::stream::Pool> rogue::interfaces::stream::PoolPtr

Shared pointer alias for Pool.

The class description is shown below:

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

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.

Subclassed by rogue::interfaces::stream::Slave

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

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

Exposed as getAllocBytes() in Python.

Returns:

Total currently allocated bytes.

uint32_t getAllocCount()

Returns total currently allocated buffer 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.

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

Services a frame allocation request from a 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.

virtual void retBuffer(uint8_t *data, uint32_t meta, uint32_t size)

Returns buffer data to the allocator.

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.

void setFixedSize(uint32_t size)

Sets fixed-size mode.

This method puts the allocator into fixed size mode.

Exposed as setFixedSize() in Python.

Parameters:

size – Fixed size value.

uint32_t getFixedSize()

Returns fixed-size allocation setting.

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.

void setPoolSize(uint32_t size)

Sets buffer pool size.

Exposed as setPoolSize() in Python.

Parameters:

size – Number of entries to keep in the pool.

uint32_t getPoolSize()

Returns configured maximum number of cached pool entries.

Exposed as getPoolSize() in Python.

Returns:

Pool size.

Public Static Functions

static void setup_python()

Registers this type with Python bindings.