dtpf::BufferGroup Class Reference

#include <BufferGroup.h>

List of all members.

---

Detailed Description

Provides an interface to a pool of BufferDescriptors.

Upstream (producer) nodes can acquire buffers from the pool, read and write to the buffers' data area, and send buffers to downstream (consumer) nodes. Consumer nodes receiving buffers can read and write to the buffers' data area and either send the buffers to further consumer nodes or release buffers back to the pool for reuse.

A BufferGroup containing buffers with 'large' data regions will use shared memory for the underlying data, while those containing buffers with 'small' data regions will not. For BufferGroups with 'large' data regions the shared memory will be used for BufferGroup information such as the DataFormat, a list of buffers, etc. 'Large' buffers are transmitted between Nodes by passing information needed to reference a particular buffer in the owning BufferGroup's shared memory region. 'Small' buffers are transmitted between nodes by sending a copy of the entire buffer, including the data region.

BufferGroup instances are created by the framework.

Public Member Functions
status_t	Map (uint32 mode)
	Map a BufferGroup's buffer data region into the calling process' virtual address space.
virtual	~BufferGroup ()
	Class destructor.
BufferGroupID	GroupID () const
	Retrieve the BufferGroupID for a BufferGroup.
DataFormat const *	Format () const
	Retrieve the DataFormat for a BufferGroup.
BufferDescriptor *	AcquireBuffer ()
	Acquire a buffer from thhis buffer group.
status_t	ReleaseBuffer (BufferDescriptor *buffer)
	Release a buffer to is owning buffer group.
Static Public Member Functions
BufferGroup *	Allocate (DataFormat *dataFormat, uint32 initialBuffers=8, uint32 maximumBuffers=24, uint32 lockFlags=AREA_NO_LOCK)
	Create a BufferGroup with the given parameters and any underlying resources needed such as shared memory.
BufferGroup *	Find (BufferGroupID id)
	Lookup a BufferGroup by ID.
status_t	Destroy (BufferGroupID id)
	Destroy a BufferGroup.
Private Member Functions
	BufferGroup ()
	Default constructor that does nothing.

---

Constructor & Destructor Documentation

virtual dtpf::BufferGroup::~BufferGroup (   )  [virtual]

Class destructor. This will delete a particular BufferGroup instance. It will not free the the framework level resources associated with the BufferGroup. In the case of BufferGroups for 'large' buffers that are use shared memory there could and probably will be multiple instances of BufferGroup that make use of the same underlying shared memory, hence the destroy by ID functionality of Destroy().

dtpf::BufferGroup::BufferGroup (   )  [private]

Default constructor that does nothing. Intentionally private to prevent client instantiation of BufferGroups.

---

Member Function Documentation

BufferDescriptor* dtpf::BufferGroup::AcquireBuffer (   )

Acquire a buffer from thhis buffer group. If no buffers are immediately available and the current count is less than the maximum, a new buffer will be allocated, otherwise this will block until a buffer is released and becomes available. Ideally there should always be a free buffer available. Returns: A pointer to a valid buffer, will return NULL if there were serious problems. The caller should not delete the returned buffer.

BufferGroup* dtpf::BufferGroup::Allocate (  DataFormat *  dataFormat, uint32  initialBuffers = 8, uint32  maximumBuffers = 24, uint32  lockFlags = AREA_NO_LOCK )  [static]

Create a BufferGroup with the given parameters and any underlying resources needed such as shared memory. The BufferGroup is assigned a unique BufferGroupID by the roster. Parameters: dataFormat  The DataFormat for buffers in the group. initialBuffers  The initial number of buffers to create. maximumBuffers  The maximum number of buffers the group can contain. lockFlags  Indicates the memory locking policy for any shared memory the group may use. Returns: A pointer to a new BufferGroup instance that the caller is responsible for deleting.

status_t dtpf::BufferGroup::Destroy (  BufferGroupID  id  )  [static]

Destroy a BufferGroup. The BufferGroup identified by id is unregistered with the roster, and any underlying shared memory it may have used is released. Parameters: id  The BufferGroupID of the BufferGroup to destroy. Returns: E_OK if the group was successfully destroyed. An appropriate error code will be returned otherwise.

BufferGroup* dtpf::BufferGroup::Find (  BufferGroupID  id  )  [static]

Lookup a BufferGroup by ID. This consults the roster to lookup the ID and get the information needed to instantiate a local copy of the BufferGroup in question. Parameters: id  The ID of the BufferGroup to find. Returns: A pointer to a BufferGroup instance corresponding to the given ID. NULL if the id could not be found or a local copy could not be instantiated.

DataFormat const* dtpf::BufferGroup::Format (   )  const

Retrieve the DataFormat for a BufferGroup. Returns: The group's DataFormat.

BufferGroupID dtpf::BufferGroup::GroupID (   )  const

Retrieve the BufferGroupID for a BufferGroup. Returns: The group's BufferGroupID.

status_t dtpf::BufferGroup::Map (  uint32  mode  )

Map a BufferGroup's buffer data region into the calling process' virtual address space. The read/write access for the new mapping can be specified to be read-only. Parameters: mode  Indicates the read/write mode of the new memory mapping. Returns: E_OK if the mapping succeeded without error.

status_t dtpf::BufferGroup::ReleaseBuffer (  BufferDescriptor *  buffer  )

Release a buffer to is owning buffer group. After this the caller should not access the buffer or its data region. Parameters: buffer  The buffer to release. Returns: E_OK if the buffer was successfully released, E_ERROR if there were problems in which case something is seriously wrong.

---

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

• Lib/BufferGroup.h

---