---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > IMM / V0-2-0

Constituent: imm     Tag: linux-gcc

---

         

---

RBM_pubdefs.h File Reference

Public definitions for the RBM package. More...

#include "PBS/RNG.h"
#include "PBS/TOC.h"
#include "PBS/WCT.h"

Include dependency graph for RBM_pubdefs.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_RBM_RingHist
	Structure for reporting ring allocation histogram. More...
struct	_RBM_RingStat
	Structure for complete RBM ring instrumentation statistics. More...
Defines
#define	RBM_L_RINGNAME   (8)
	Maximum length of ring name (incl. '\0').
Typedefs
typedef _RBM_Ring	RBM_Ring
	Typedef for struct _RBM_Ring.
typedef unsigned int	RBM_cb_ScanRing (void *prm, RBM_Ring *rcb)
	Signature for an RBM memory ring scan routine.
typedef void	RBM_cb_StopRing (void *prm)
	Signature for an ring buffer manager stop completion routine.
typedef _RBM_RingStat	RBM_RingStat
	Typedef for struct _RBM_RingStat.
typedef _RBM_RingHist	RBM_RingHist
	Typedef for struct _RBM_RingHist.
Functions
void *	RBM_alloc (RBM_Ring *rcb, unsigned int siz, unsigned int *status)
	Allocate a packet from a managed ring buffer.
void *	RBM_allocITC (RBM_Ring *rcb, unsigned int siz, void **rtn, void **cb0, void **cb1, void **cb2)
	Allocate memory packet without timeout (ITC courtesy entry point).
void *	RBM_allocW (RBM_Ring *rcb, unsigned int siz, unsigned int *status)
	Allocate a packet from a managed ring buffer.
void *	RBM_allocW_toc (RBM_Ring *rcb, unsigned int siz, const TOC *toc, unsigned int *status)
	Allocate a packet from a managed ring buffer.
unsigned int	RBM_createRing (RBM_Ring **rcb, const char *ringName, unsigned int ringSize, unsigned int ringUnder, unsigned int ringOver, unsigned int ringAlign, RNG_type typ)
	Create a managed ring buffer.
unsigned int	RBM_deleteRing (RBM_Ring *rcb)
	Delete a managed ring buffer (and release its resources).
unsigned int	RBM_free (RBM_Ring *rcb, void *pkt, unsigned int siz)
	Free memory back to a managed ring buffer.
RBM_Ring *	RBM_getRingHandle (const char *name)
	Return the ring handle corresponding to a ring name.
unsigned int	RBM_getRingHist (RBM_Ring *rcb, RBM_RingHist *rhb)
	Get the contents of the histogram block for a ring.
const char *	RBM_getRingName (RBM_Ring *rcb)
	Return the name of a managed ring buffer.
unsigned int	RBM_getRingStat (RBM_Ring *rcb, RBM_RingStat *rsb, unsigned int reset)
	Get the contents of the statistics block for a managed ring buffer.
unsigned int	RBM_initialize (void)
	Initialize the memory pool manager.
unsigned int	RBM_scanRing (RBM_cb_ScanRing *rtn, void *prm)
	Scan through the list of managed ring buffers.
unsigned int	RBM_startRing (RBM_Ring *rcb)
	Start a managed ring buffer.
unsigned int	RBM_stopRing (RBM_Ring *rcb, RBM_cb_StopRing *ringRtn, void *ringPrm)
	Stop a managed ring buffer.

---

Detailed Description

Public definitions for the RBM package.

CVS $Id: RBM_pubdefs.h,v 1.2 2005/03/25 01:01:41 apw Exp $

Author:

A.P.Waite

---

Function Documentation

void * RBM_alloc (  RBM_Ring *  rcb, unsigned int  siz, unsigned int *  status )

Allocate a packet from a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block siz  (in) Number of bytes to allocate status  (out) Completion status (pointer can be NULL) Return values: NULL  Memory allocation failed x  Pointer to allocated memory Values returned through status parameter Return values: RBM_RINGDRY  No memory left in ring to satisfy allocation RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state started RBM_RINGSIZE  Ring not big enough RBM_SUCCESS  Success RBM_alloc() allocates a memory packet from an RBM memory ring without pending.

Here is the call graph for this function:

void * RBM_allocITC (  RBM_Ring *  rcb, unsigned int  siz, void **  rtn, void **  cb0, void **  cb1, void **  cb2 )

Allocate memory packet without timeout (ITC courtesy entry point). Parameters: rcb  (in) Ring buffer manager control block siz  (in) Number of bytes to allocate rtn  (out) Processing completion callback routine cb0  (out) Processing completion callback user parameter 0 cb1  (out) Processing completion callback user parameter 1 cb2  (out) Processing completion callback user parameter 2 Return values: NULL  Memory allocation failed x  Pointer to allocated memory RBM_allocITC() is a courtesy entry point, compatible with the signature for an ITC "abstract memory allocator". In keeping with ITC's planned usage, this is an allocation without wait. The callback is set up to simply free the memory. rtn is set to RBM_freeITC(), cb0 is set to the ring control block rcb, cb1 is set to the number of bytes allocated. cb2 is unused.

Here is the call graph for this function:

void * RBM_allocW (  RBM_Ring *  rcb, unsigned int  siz, unsigned int *  status )

Allocate a packet from a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block siz  (in) Number of bytes to allocate status  (out) Completion status (pointer can be NULL) Return values: NULL  Memory allocation failed x  Pointer to allocated memory Values returned through status parameter Return values: RBM_RINGDRY  No memory left in ring to satisfy allocation RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state started RBM_RINGSIZE  Ring not big enough RBM_SUCCESS  Success RBM_alloc() allocates a memory packet from an RBM memory ring with infinite pending.

Here is the call graph for this function:

void * RBM_allocW_toc (  RBM_Ring *  rcb, unsigned int  siz, const TOC *  toc, unsigned int *  status )

Allocate a packet from a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block siz  (in) Number of bytes to allocate toc  (in) Time-out control status  (out) Completion status (pointer can be NULL) Return values: NULL  Memory allocation failed x  Pointer to allocated memory Values returned through status parameter Return values: RBM_RINGDRY  No memory left in ring to satisfy allocation RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state started RBM_RINGSIZE  Ring not big enough RBM_SUCCESS  Success RBM_allocW_toc() allocates a memory packet from an RBM memory pring. This is the most general entry point, providing both timeout control and an explanation in case of failure (via the status parameter). For simpler applications that don't require timeout control, the entry points RBM_alloc() and RBM_allocW() are more appropriate.

Here is the call graph for this function:

unsigned int RBM_createRing (  RBM_Ring **  rcb, const char *  ringName, unsigned int  ringSize, unsigned int  ringUnder, unsigned int  ringOver, unsigned int  ringAlign, RNG_type  typ )

Create a managed ring buffer. Parameters: rcb  (out) Ring buffer manager, ring control block ringName  (in) Ring buffer name ringSize  (in) Ring buffer memory size (bytes) ringUnder  (in) Ring buffer underflow area (bytes) ringOver  (in) Ring buffer overflow area (bytes) ringAlign  (in) Ring buffer alignment typ  (in) Ring pend type Return values: RBM_ALOCFAIL  Memory allocation failure RBM_FPAINIT  FPA initialization failure RBM_NOTINIT  RBM system not initialized RBM_RNAMLEN  Ring name length out of valid range RBM_RNAMNULL  Ring name is a NULL pointer RBM_RNAMSNTX  Ring name s has invalid syntax RBM_SUCCESS  Success RBM_createRing() creates a managed ring buffer.

Here is the call graph for this function:

unsigned int RBM_deleteRing (  RBM_Ring *  rcb  )

Delete a managed ring buffer (and release its resources). Parameters: rcb  (in) Ring buffer manager control block Return values: RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state initialized RBM_SUCCESS  Success RBM_deleteRing() deletes a managed ring buffer and releases all the associated resources.

unsigned int RBM_free (  RBM_Ring *  rcb, void *  pkt, unsigned int  siz )

Free memory back to a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block pkt  (in) Pointer to memory to free siz  (in) Length of memory to free Return values: RBM_RINGMISS  Packet pointer not valid in this ring RBM_RINGPTR  Ring control block pointer invalid RBM_SUCCESS  Success RBM_free() frees a packet back to a managed ring buffer.

Here is the call graph for this function:

RBM_Ring * RBM_getRingHandle (  const char *  name  )

Return the ring handle corresponding to a ring name. Parameters: name  (in) Name of ring buffer to search for RBM_getRingHandle() searches through the list of ring buffers for the one named name and if found, returns its handle. Any error results in a NULL return value.

unsigned int RBM_getRingHist (  RBM_Ring *  rcb, RBM_RingHist *  rhb )

Get the contents of the histogram block for a ring. Parameters: rcb  (in) Ring buffer manager control block rhb  (out) Ring buffer manager histogram block Return values: RBM_NOTINIT  RBM system not initialized RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSIZE  Ring doesn't have an allocator that size RBM_SUCCESS  Success RBM_getRingHist() returns a ring's histogram block into a block of caller provided memory, along with time stamps. The histogram accumulates requested allocation sizes (in powers of two). It accumulates continuously while the ring is started. If the ring is stopped, the histogram for the most recent "started" period is returned. If the ring has never been started, a zeroed histogram block is returned. Any errors also result in a zeroed histogram block being returned.

const char * RBM_getRingName (  RBM_Ring *  rcb  )

Return the name of a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block Returns: A pointer to the ring name. Any error (NULL ring control block pointer, invalid ring control block pointer, ...) causes the routine to return a pointer to the string <nonam>.

unsigned int RBM_getRingStat (  RBM_Ring *  rcb, RBM_RingStat *  rsb, unsigned int  reset )

Get the contents of the statistics block for a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block rsb  (out) Ring buffer manager statistics block reset  (in) Reset flag (0/1 => no reset/reset) Return values: RBM_NOTINIT  RBM system not initialized RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSIZE  Ring doesn't have an allocator that size RBM_SUCCESS  Success RBM_getRingStat() returns a ring buffer's statistics block into a block of caller provided memory. Statistics include free memory high and low water marks since the ring was started. These can be of marginal utility (the hwm never moves off the original number of bytes allocated, and if the ring exhausts, the lwm gets stuck on zero). The statistics therefore keep a second, resettable set of high and low water marks. Setting the reset parameter to this routine will cause them to reset to the current free byte count (and take a timestamp of when the reset occured). These are the only statistics affected by the reset flag. All other statistics accumulate from ring buffer start. If called while the ring buffer is not started, the statistics returned apply to the most recent "started" period. If the memory ring has never been started, a zeroed statistice block is returned. Any errors also result in a zeroed statistics block being returned.

unsigned int RBM_initialize (  void   )

Initialize the memory pool manager. Return values: RBM_ALOCFAIL  Memory allocation failure RBM_MUALOCFL  Mutex allocation failure RBM_SUCCESS  Success RBM_initialize() initializes the memory pool manager.

unsigned int RBM_scanRing (  RBM_cb_ScanRing *  rtn, void *  prm )

Scan through the list of managed ring buffers. Parameters: rtn  (in) Scan callback routine prm  (in) Scan callback parameter Return values: RBM_NOTINIT  RBM system not initialized RBM_PARMNULL  Callback routine is a NULL pointer RBM_SUCCESS  Success RBM_scanRing() scans though the list of known managed ring buffers and calls back the user provided routine for each in turn. A non-success return code from the user's callback routine aborts the scan.

unsigned int RBM_startRing (  RBM_Ring *  rcb  )

Start a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block Return values: RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state initialized RBM_SUCCESS  Success RBM_startRing() starts a managed ring buffer (makes it available for allocation requests).

unsigned int RBM_stopRing (  RBM_Ring *  rcb, RBM_cb_StopRing *  ringRtn, void *  ringPrm )

Stop a managed ring buffer. Parameters: rcb  (in) Ring buffer manager control block ringRtn  (in) Completion callback routine ringPrm  (in) Completion callback parameter Return values: RBM_RINGPTR  Ring control block pointer invalid RBM_RINGSTAT  Ring control block not in state started RBM_SUCCESS  Success RBM_stopRing() starts the process of stopping a managed ring buffer. Note that this is not instantaneous. The ring is not officially stopped until all memory managed by the ring has been returned. If the caller needs to synchronize on exactly when the ring transitions from RBM_MEM_STOPPING to RBM_MEM_INITIALIZED, then please use the completion callback.

Here is the call graph for this function:

---