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

Constituent: imm     Tag: rad750

Interface   Data Structures   File List   Data Fields   Globals  

RBM_ring.c File Reference

Ring buffer manager control routines. More...

#include <ctype.h>
#include <string.h>
#include "PBS/MBA.h"
#include "PBS/MTX.h"
#include "PBS/RNG.h"
#include "PBS/RW.ih"
#include "MSG/MSG_pubdefs.h"
#include "IMM/RBM_pubdefs.h"
#include "IMM/RBM_msgs.h"
#include "RBM_prvdefs.h"

Include dependency graph for RBM_ring.c:

Include dependency graph

Functions

unsigned int validName (const char *name, const char *func)
 Validate a ring name.

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

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

void RBM_stopCheck (RBM_Ring *rcb)
 Check if ring buffer is drained (if it is, complete stop processing).

unsigned int RBM_stopRing (RBM_Ring *rcb, RBM_cb_StopRing *ringRtn, void *ringPrm)
 Stop a managed ring buffer.


Variables

const char * RBM_mem_states [RBM_L_MEM_STATES]
 String constants for RBM ring buffer memory states.

Detailed Description

Ring buffer manager control routines. 

CVS $Id: RBM_ring.c,v 1.2 2005/03/25 01:01:41 apw Exp $
Author:
A.P.Waite
RBM_ring.c provides the ring buffer manager ring control routines.

Function Documentation

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.

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_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).

void RBM_stopCheck (  RBM_Ring *  rcb  ) 
 

Check if ring buffer is drained (if it is, complete stop processing).

Parameters:
rcb (in) Ring buffer manager control block
RBM_stopCheck() checks a ring to see if all the memory hass been freed, and if so, completes the process of stopping the ring.

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:

unsigned int validName (  const char *  name,
const char *  func
)  [static]
 

Validate a ring name.

Parameters:
name (in) Rgin name
func (in) Name of calling routine
Return values:
RBM_RNAMLEN Ring name length out of valid range
RBM_RNAMNULL Ring name is a NULL pointer
RBM_RNAMSNTX Ring name has invalid syntax
RBM_SUCCESS Success
RBM_validName() validates a memory ring name.

Variable Documentation

const char* RBM_mem_states[RBM_L_MEM_STATES]
 

Initial value:

{
    "uninitialized",
    "initialized",
    "started",
    "stopping"
}
String constants for RBM ring buffer memory states.

Generated on Sun Jul 17 07:41:53 2005 by doxygen 1.3.3