FPM_pubdefs.h File Reference

Public definitions for the FPM package. More...

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

Include dependency graph for FPM_pubdefs.h:

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


Data Structures
struct	_FPM_AllocStat
	Structure for per allocator instrumentation statistics. More...
struct	_FPM_PoolDsc
	Structure to describe a memory pool. More...
struct	_FPM_PoolHist
	Structure for per pool instrumentation counts (histogram). More...
struct	_FPM_PoolStat
	Structure for complete FPM pool instrumentation statistics. More...
Defines
#define	FPM_L_POOLNAME (8)
	Maximum length of pool name (incl. '\0').
Typedefs
typedef _FPM_Pool	FPM_Pool
	Typedef for struct _FPM_Pool.
typedef unsigned int	FPM_cb_ScanPool (void prm, FPM_Pool pcb)
	Signature for an FPM memory pool scan routine.
typedef void	FPM_cb_StopPool (void *prm)
	Signature for an FPM memory pool stop completion routine.
typedef _FPM_AllocStat	FPM_AllocStat
	Typedef for struct _MSG_AllocStat.
typedef _FPM_PoolStat	FPM_PoolStat
	Typedef for struct _MSG_PoolStat.
typedef _FPM_PoolDsc	FPM_PoolDsc
	Typedef for struct _FPM_PoolDsc.
typedef _FPM_PoolHist	FPM_PoolHist
	Typedef for struct _MSG_PoolHist.
Functions
void *	FPM_alloc (FPM_Pool pcb, unsigned int siz, unsigned int status)
	Allocate a packet from an FPM memory pool.
void *	FPM_allocITC (FPM_Pool pcb, unsigned int siz, void rtn, void cb0, void cb1, void *cb2)
	Allocate memory packet without timeout (ITC courtesy entry point).
void *	FPM_allocW (FPM_Pool pcb, unsigned int siz, unsigned int status)
	Allocate a packet from an FPM memory pool.
void *	FPM_allocW_toc (FPM_Pool pcb, unsigned int siz, const TOC toc, unsigned int *status)
	Allocate a packet from an FPM memory pool.
unsigned int	FPM_createPool (FPM_Pool *pcb, const char poolNam, unsigned int poolCnt, FPM_PoolDsc *poolDsc, FPA_type typ)
	Create memory pool from collection of fixed packet allocators.
unsigned int	FPM_deletePool (FPM_Pool *pcb)
	Delete a memory pool (and release its resources).
unsigned int	FPM_free (FPM_Pool pcb, void pkt)
	Free a packet back to an FPM memory pool.
FPM_Pool *	FPM_getPoolHandle (const char *name)
	Return the pool handle corresponding to a pool name.
unsigned int	FPM_getPoolHist (FPM_Pool pcb, FPM_PoolHist phb)
	Get the contents of the histogram block for a pool.
const char *	FPM_getPoolName (FPM_Pool *pcb)
	Return the name of a memory pool.
unsigned int	FPM_getPoolStat (FPM_Pool pcb, FPM_PoolStat psb, unsigned int reset)
	Get the contents of the statistics block for a pool.
unsigned int	FPM_initialize (void)
	Initialize the memory pool manager.
unsigned int	FPM_scanPool (FPM_cb_ScanPool rtn, void prm)
	Scan through the list of memory pools.
unsigned int	FPM_sizeofPoolStat (FPM_Pool *pcb)
	Return the size (bytes) neede to hols a pool statistics block.
unsigned int	FPM_startPool (FPM_Pool *pcb)
	Start a fixed packet allocation memory pool.
unsigned int	FPM_stopPool (FPM_Pool pcb, FPM_cb_StopPool poolRtn, void *poolPrm)
	Stop a fixed packet allocation memory pool.

Detailed Description

Public definitions for the FPM package.

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

Author:: A.P.Waite

Function Documentation

void* FPM_alloc ( FPM_Pool * pcb,

unsigned int siz,

unsigned int * status

)

Allocate a packet from an FPM memory pool.

Parameters:

pcb (in) Memory pool 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:

FPM_POOLDRY No packets left in pool to satisfy allocation

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state started

FPM_POOLSIZE Pool has no allocator big enough

FPM_SUCCESS Success

FPM_alloc() allocates a memory packet from an FPM memory pool without pending.

Here is the call graph for this function:

void* FPM_allocITC ( FPM_Pool * pcb,

unsigned int siz,

void ** rtn,

void ** cb0,

void ** cb1,

void ** cb2

)

Allocate memory packet without timeout (ITC courtesy entry point).

Parameters:

pcb (in) Memory pool 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

FPM_alloc() 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 FPM_freeITC() and cb0 is set to the pool control block pcb. Other callback parameters are set to NULL.

Here is the call graph for this function:

void* FPM_allocW ( FPM_Pool * pcb,

unsigned int siz,

unsigned int * status

)

Allocate a packet from an FPM memory pool.

Parameters:

pcb (in) Memory pool 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:

FPM_POOLDRY No packets left in pool to satisfy allocation

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state started

FPM_POOLSIZE Pool has no allocator big enough

FPM_SUCCESS Success

FPM_allocW() allocates a memory packet from an FPM memory pool with infinite pending.

Here is the call graph for this function:

void* FPM_allocW_toc ( FPM_Pool * pcb,

unsigned int siz,

const TOC * toc,

unsigned int * status

)

Allocate a packet from an FPM memory pool.

Parameters:

pcb (in) Memory pool 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:

FPM_POOLDRY No packets left in pool to satisfy allocation

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state started

FPM_POOLSIZE Pool has no allocator big enough

FPM_SUCCESS Success

FPM_allocW_toc() allocates a memory packet from an FPM memory pool. 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 FPM_alloc() and FPM_allocW() are more appropriate.

Here is the call graph for this function:

unsigned int FPM_createPool ( FPM_Pool ** pcb,

const char * poolNam,

unsigned int poolCnt,

FPM_PoolDsc * poolDsc,

FPA_type typ

)

Create memory pool from collection of fixed packet allocators.

Parameters:

pcb (out) Memory pool control block

poolNam (in) Pool name

poolCnt (in) Pool allocator descriptor count

poolDsc (in) Pool allocator descriptors

typ (in) FPA pend type

Return values:

FPM_ALOCFAIL Memory allocation failure

FPM_CTLSTAT FPM control block not in state initialized

FPM_FPAINIT FPA initialization failure

FPM_NOTINIT FPM system not initialized

FPM_PDSCCNT Pool descriptor list size out of range

FPM_PDSCORDR Pool descriptor list not sorted in ascending order

FPM_PDSCPKTN Pool descriptor allocator count below minimum

FPM_PDSCPKTS Pool descriptor allocator size out of range

FPM_PNAMLEN Pool name length out of valid range

FPM_PNAMNULL Pool name is a NULL pointer

FPM_PNAMSNTX Pool name s has invalid syntax

FPM_SUCCESS Success

FPM_createPool() creates a memory pool based on the memory pool descriptors passed to the routine. Each descriptor descibes one fixed packet allocator, giving the fixed packet size (expressed in powers of two) and packet count. The descriptors are treated as an array, and /e must describe the fixed packet allocators in order of increasing packet size.

Here is the call graph for this function:

unsigned int FPM_deletePool ( FPM_Pool * pcb )

Delete a memory pool (and release its resources).

Parameters:

pcb (in) Memory pool control block

Return values:

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state initialized

FPM_SUCCESS Success

FPM_deletePool() deletes an memory pool and releases all the associated resources.

Here is the call graph for this function:

unsigned int FPM_free ( FPM_Pool * pcb,

void * pkt

)

Free a packet back to an FPM memory pool.

Parameters:

pcb (in) Memory pool control block

pkt (in) Packet to free

Return values:

FPM_POOLMISS Packet pointer not valid in this pool

FPM_POOLPTR Pool control block pointer invalid

FPM_SUCCESS Success

FPM_free() frees a packet back to an FPM memory pool. By a not so strange coincidence, it also has the correct signature for use as an ITC memory free routine.

Here is the call graph for this function:

FPM_Pool * FPM_getPoolHandle ( const char * name )

Return the pool handle corresponding to a pool name.

Parameters:

name (in) Name of memory pool to search for

FPM_getPoolHandle() searches through the list of pools for the one named name and if found, returns its handle. Any error results in a NULL return value.

unsigned int FPM_getPoolHist ( FPM_Pool * pcb,

FPM_PoolHist * phb

)

Get the contents of the histogram block for a pool.

Parameters:

pcb (in) Memory pool control block

phb (out) Memory pool histogram block

Return values:

FPM_NOTINIT FPM system not initialized

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSIZE Pool doesn't have an allocator that size

FPM_SUCCESS Success

FPM_getPoolHist() returns a pool'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 pool is started. If the pool is stopped, the histogram for the most recent "started" period is returned. If the pool has never been started, a zeroed histogram block is returned.
Any errors also result in a zeroed histogram block being returned.

const char * FPM_getPoolName ( FPM_Pool * pcb )

Return the name of a memory pool.

Parameters:

pcb (in) Memory pool control block

Returns:
A pointer to the pool name. Any error (NULL pool control block pointer, invalid pool control block pointer, ...) causes the routine to return a pointer to the string <nonam>.

unsigned int FPM_getPoolStat ( FPM_Pool * pcb,

FPM_PoolStat * psb,

unsigned int reset

)

Get the contents of the statistics block for a pool.

Parameters:

pcb (in) Memory pool control block

psb (out) Pool statistics block

reset (in) Reset flag (0/1 => no reset/reset)

Return values:

FPM_NOTINIT FPM system not initialized

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSIZE Pool doesn't have an allocator that size

FPM_SUCCESS Success

FPM_getPoolStat() returns a pool's statistics block into a block of caller provided memory. To find out how big the user provided piece of memory should be, use FPM_sizeofPoolStat().
Pool statistics include allocation high and low water marks since the pool was started. These can be of marginal utility (the hwm never moves off the original number of packets allocated, and if the pool 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 currently allocated number of packets (and take a timestamp of when the reset occured). These are the only statistics affected by the reset flag. All other statistics accumulate from memory pool start.
If called while the memory pool is not started, the statistics returned apply to the most recent "started" period. If the memory pool has never been started, a zeroed statistice block is returned.
Any errors also result in a zeroed statistics block being returned.

unsigned int FPM_initialize ( void )

Initialize the memory pool manager.

Return values:

FPM_ALOCFAIL Memory allocation failure

FPM_MUALOCFL Mutex allocation failure

FPM_SUCCESS Success

FPM_initialize() initializes the memory pool manager.

unsigned int FPM_scanPool ( FPM_cb_ScanPool * rtn,

void * prm

)

Scan through the list of memory pools.

Parameters:

rtn (in) Scan callback routine

prm (in) Scan callback parameter

Return values:

FPM_NOTINIT FPM system not initialized

FPM_PARMNULL Callback routine is a NULL pointer

FPM_SUCCESS Success

FPM_scanPool() scans though the list of known pools 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 FPM_sizeofPoolStat ( FPM_Pool * pcb )

Return the size (bytes) neede to hols a pool statistics block.

Parameters:

pcb (in) Memory pool control block

Return values:

0 Invalid request (pcb makes no sense)

x Size of memory required

unsigned int FPM_startPool ( FPM_Pool * pcb )

Start a fixed packet allocation memory pool.

Parameters:

pcb (in) Memory pool control block

Return values:

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state initialized

FPM_SUCCESS Success

FPM_startPool() starts a memory pool (make it available for allocation requests).

unsigned int FPM_stopPool ( FPM_Pool * pcb,

FPM_cb_StopPool * poolRtn,

void * poolPrm

)

Stop a fixed packet allocation memory pool.

Parameters:

pcb (in) Memory pool control block

poolRtn (in) Completion callback routine

poolPrm (in) Completion callback parameter

Return values:

FPM_POOLPTR Pool control block pointer invalid

FPM_POOLSTAT Pool control block not in state initialized

FPM_SUCCESS Success

FPM_stopPool() starts the process of stopping a memory pool. Note that this is not instantaneous. The pool is not officially stopped until all packets managed by the pool are back on the free lists. If the caller needs to synchronize on exactly when the pool transitions from FPM_MEM_STOPPING to FPM_MEM_INITIALIZED, then please use the completion callback.

Here is the call graph for this function:

Generated on Thu Mar 24 20:33:42 2005 by

1.3.3

FPM_pubdefs.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Function Documentation