rvobjpool.h

基于h323协议的软phone

/***********************************************************************
Filename   : objpool.h
Description: objpool header file
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
	{name: ObjPool}
	{superpackage: CUtils}
	{include: rvobjpool.h}
	{description:	
		{p: This module provides functions for creating and manipulating
			object pools. Memory for the pool will be allocated and freed
			via callback functions.}
		{p:	To make a object (structure) usable in a pool, an element of type
			RvObjPoolElement must be declared in that structure. You may also
			need functions for constructing and destructing the object.}
		{p: There are three types of pools:}
		{bulletlist:
			{item:  FIXED: This creates a fixed size pool. Items may only be
					added to the pool with the RvObjPoolAddItems and
					RvObjPoolAddPages functions. Items may only be removed
					with the RvObjPoolSalvage function (and only if the salvage
					option has been enabled). FIXED pools are subject to the
					maxitems and minitems settings but those settings will
					rarely be used with fixed pools.}
			{item:  EXPANDING: This creates a pool which expands (by adding
					pages) as needed. Items may also be added to the pool with
					the RvObjPoolAddItems and RvObjPoolAddPages functions. Items
					may only be removed with the RvObjPoolSalvage function (and
					only if the salvage option has been enabled). The maxitems
					and minitems settings may be used to put boundries on the
					size of the pool.}
			{item:  DYNAMIC: This creates a pool which expands exactly like
					and EXPANDING pool but also has the ability to removed
					unused pages. The freelevel setting determines when a
					page should be released. Items may also be added to the
					pool with the RvObjPoolAddItems and RvObjPoolAddPages
					functions and may removed with the RvObjPoolSalvage
					function. The maxitems and minitems settings may be used
					to put boundries on the size of the pool.}
		}
	}
	{notes:
		{note:  This module does no locking at all. The locking of the
				object pool is the responsibility of the user.}
	}
}
$*/
#ifndef RV_OBJPOOL_H
#define RV_OBJPOOL_H

#include "rvtypes.h"
#include "rvobjlist.h"


/*$
{type:
	{name: RvObjPoolElement}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:	
		{p: An element of this data type must be declared in the
			structure to be put into a pool.}
		{p: The information stored in this element is only used while a
			particular object is actually in the pool. The information
			stored in that element does not need to be maintained when
			the object is not in the pool.}
		{p: An object type can be used to create multiple pools but
			any individual object can only be in one pool, thus there
			is never a need for more than one element in a structure.}
	}
}
$*/
typedef RvObjListElement RvObjPoolElement;


/*$
{type:
	{name: RvObjPoolFuncs}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:	
		{p: A structure containing callback information for an object pool. This structure
			must be completely filled out before passing it to RvObjPoolConstruct.}
		{p: Normal operation of a pool will constist of creating and destroying pages. Each
			page constains a given number of the objects in the pool. When a page is created,
			the pagealloc callback with the number of bytes required for the page followed by
			a call to objconstruct for each object in the new page. When destroying a page,
			the objdestruct will be called on each object, then pagefree will be called for
			the page.}
	}
	{attributes scope="public":
		{attribute: {t: void *()(void *objptr, void *data)} {n: objconstruct} {d: Callback to construct objptr. Return objptr or NULL for failure.}}
		{attribute: {t: void  ()(void *objptr, void *data)} {n: objdestruct} {d: Callback to destruct objptr.}}
		{attribute: {t: void *()(RvSize_t size, void *data)} {n: pagealloc} {d: Callback to allocate size bytes of memory. Return pointer to memory or NULL for failure.}}
		{attribute: {t: void  ()(void *ptr, void *data} {n: pagefree} {d: Callback to free the memory at ptr.}}
		{attribute: {t: void *} {n: objconstructdata} {d: User data parameter passed into objconstruct.}}
		{attribute: {t: void *} {n: objdestructdata} {d: User data parameter passed into  objdestruct.}}
		{attribute: {t: void *} {n: pageallocdata} {d: User data parameter passed into pagealloc.}}
		{attribute: {t: void *} {n: pagefreedata} {d: User data parameter passed into pagefree.}}
	}
	{notes:
		{note: The objconstruct and objdestruct calls are optional. Setting them to NULL
				simply indicates that there is no constructor and/or destructor for the
				object type being pooled.}
	}
}
$*/
typedef struct {
	void *(*objconstruct)(void *objptr, void *data); /* (optional) Construct object in pool. Return pointer to item, NULL = failed. */
	void  (*objdestruct)(void *objptr, void *data);  /* (optional) Destruct object in pool. */
	void *(*pagealloc)(RvSize_t size, void *data);   /* Allocate page of memory. Return pointer to page memory, NULL = failed. */
	void  (*pagefree)(void *ptr, void *data);        /* Free page of memory. */
	void *objconstructdata; /* User data parameter passed into objconstruct */
	void *objdestructdata;  /* User data parameter passed into objdestruct */
	void *pageallocdata;    /* User data parameter passed into pagealloc */
	void *pagefreedata;     /* User data parameter passed into pagefree */
} RvObjPoolFuncs;


/*$
{type:
	{name: RvObjPool}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:	
		{p: An object pool object.}
	}
}
$*/
typedef struct {
	RvObjList pagelist;       /* List of pages in pool */
	RvObjList freelist;       /* List of available items */
	RvObjPoolFuncs callbacks; /* User defined function callbacks */
	RvSize_t itemsize;        /* Size of each item */
	RvSize_t pageitems;       /* Number of items per page */
	RvSize_t pagesize;        /* Size (in bytes) of each page */
	RvSize_t blocksize;       /* size of memory block used for each item (calculated) */
	RvBool autoexpand;        /* RV_TRUE if pages automatically created as needed */
	RvBool autoreduct;        /* RV_TRUE if pages should be removed automatically */
	RvSize_t maxitems;        /* Number of items in pool will never exceed this value. */
	RvSize_t minitems;        /* Number of items in pool will never go below this value. */
	RvBool allowsalvage;      /* RV_TRUE if pages can be removed */
	RvSize_t reductlevel;     /* automatically removing a page will not leave less than */
	                          /*   reductlevel free items per 100 */
} RvObjPool;

/* Pool Types: options are passed in via the data parameter */
/*   FIXED: Pages only added by PageAdd commands */
/*   EXPANDING: Pages added as needed */
/*   DYNAMIC: Pages added as needed and removed automatically. */
#define RV_OBJPOOL_TYPE_FIXED RvIntConst(0)
#define RV_OBJPOOL_TYPE_EXPANDING RvIntConst(1)
#define RV_OBJPOOL_TYPE_DYNAMIC RvIntConst(2)

/* Options for salvage setting. */
#define RV_OBJPOOL_SALVAGE_ALLOWED RV_TRUE
#define RV_OBJPOOL_SALVAGE_NEVER RV_FALSE

#if defined(__cplusplus)
extern "C" {
#endif 

/* Prototypes: See documentation blocks below for details. */
RvObjPool *RvObjPoolConstruct(RvObjPool *objpool, void *itemtemp, RvObjPoolElement *elementptr, RvObjPoolFuncs *callbacks, RvSize_t itemsize, RvSize_t pageitems, RvSize_t pagesize, RvInt pooltype, RvBool salvage, RvSize_t maxitems, RvSize_t minitems, RvSize_t freelevel);
RvBool RvObjPoolDestruct(RvObjPool *objpool);
RvSize_t RvObjPoolTotalItems(RvObjPool *objpool);
RvSize_t RvObjPoolFreeItems(RvObjPool *objpool);
RvSize_t RvObjPoolTotalPages(RvObjPool *objpool);
RvSize_t RvObjPoolItemsPerPage(RvObjPool *objpool);
RvSize_t RvObjPoolItemBlockSize(RvObjPool *objpool);
RvSize_t RvObjPoolPageSize(RvObjPool *objpool);
RvSize_t RvObjPoolGetMaxitems(RvObjPool *objpool);
RvBool RvObjPoolSetMaxitems(RvObjPool *objpool, RvSize_t newmax);
RvSize_t RvObjPoolGetMinitems(RvObjPool *objpool);
RvBool RvObjPoolSetMinitems(RvObjPool *objpool, RvSize_t newmin);
RvSize_t RvObjPoolGetFreelevel(RvObjPool *objpool);
RvBool RvObjPoolSetFreelevel(RvObjPool *objpool, RvSize_t newlevel);
RvSize_t RvObjPoolAddItems(RvObjPool *objpool, RvSize_t numitems);
RvSize_t RvObjPoolAddPages(RvObjPool *objpool, RvSize_t numpages);
RvSize_t RvObjPoolSalvage(RvObjPool *objpool);
void *RvObjPoolGetItem(RvObjPool *objpool);
RvBool RvObjPoolReleaseItem(RvObjPool *objpool, void *item);

#if defined(RV_TEST_CODE)
void RvObjPoolTest(void);
#endif /* RV_TEST_CODE */

#if defined(__cplusplus)
}
#endif 
/*$
{function:
	{name: RvObjPoolConstruct}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:
		{p: Constructs an object pool.}
	}
	{proto: RvObjPool *RvObjPoolConstruct(RvObjPool *objpool, void *itemtemp, RvObjPoolElement *elementptr, RvObjPoolFuncs *callbacks, RvSize_t itemsize, RvSize_t pageitems, RvSize_t pagesize, RvInt pooltype, RvBool salvage, RvSize_t maxitems, RvSize_t minitems, RvSize_t freelevel);}
	{params:
		{param: {n: objpool} {d: Pointer to object pool object to construct.}}
		{param: {n: itemtemp} {d: Pointer to an object of the type to be stored in the pool.}}
		{param: {n: elementptr} {d: Pointer to the element within itemtemp to use for this pool.}}
		{param: {n: callbacks} {d: Pointer to structure with callback information.}}
		{param: {n: itemsize} {d: The size of the item to being stored in the pool.}}
		{param: {n: pageitems} {d: Number of items per page (0 = calculate from pagesize).}}
		{param: {n: pagesize} {d: Size of each page (0 = calculate from pageitems).}}
		{param: {n: pooltype} {d: The type of block pool: RV_OBJPOOL_TYPE_FIXED, RV_OBJPOOL_TYPE_EXPANDING, or RV_OBJPOOL_TYPE_DYNAMIC.}}
		{param: {n: salvage} {d: Set to RV_OBJPOOL_SALVAGE_ALLOWED to allow page salvage, otherwise RV_OBJPOOL_SALVAGE_NEVER.
									Must be set to RV_OBJPOOL_SALVAGE_ALLOWED for DYNAMIC pools. Enabling this
									options incurs some additional memory overhead.}}
		{param: {n: maxitems} {d: Number of items never to exceed this value (0 = no max).}}
		{param: {n: minitems} {d: Number of items never to go below this value.}}
		{param: {n: freelevel} {d: Minumum number of items free per 100 (0 to 100). Used for DYNAMIC pools only.}}
	}
	{returns: A pointer to the object pool object or, if there is an error, NULL.}
	{notes:
		{note:  The itemtemp and elementptr pointers are simply used to find the offset
				within the structure where the RvObjPoolElement element is located.
				Anything the itemtemp pointer may point is is never touched.}
		{note:  The callbacks structure will be copied so there is no need to maintain this
				structure after construction.}
		{note:  Disabling the salvage option reduces memory overhead. For DYNAMIC pools
				the salvage option must be enabled.}
	}
}
$*/
/*$
{function:
	{name: RvObjPoolDestruct}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:
		{p: Destructs an object pool.}
	}
	{proto: RvBool RvObjPoolDestruct(RvObjPool *objpool);}
	{params:
		{param: {n: objpool} {d: Pointer to object pool object to be destructed.}}
	}
	{returns: RV_TRUE if object pool has been destructed, RV_FALSE if not.}
	{notes:
		{note:  A pool can only be destructed if all items have been returned to
				the pool. Trying to destroy a pool with items missing will simply
				do nothing and return a value of RV_FALSE.}
	}
}
$*/
/*$
{function:
	{name: RvObjPoolTotalItems}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:
		{p: Gets the total number of items in an object pool.}
	}
	{proto: RvSize_t RvObjPoolTotalItems(RvObjPool *objpool);}
	{params:
		{param: {n: objpool} {d: Pointer to object pool to get information about.}}
	}
	{returns: Total number of items in the object pool.}
}
$*/
/*$
{function:
	{name: RvObjPoolFreeItems}
	{superpackage: ObjPool}
	{include: rvobjpool.h}
	{description:
		{p: Gets the number of items currently available in an object pool.}
	}
	{proto: RvSize_t RvObjPoolFreeItems(RvObjPool *objpool);}
	{params:
		{param: {n: objpool} {d: Pointer to object pool to get information about.}}
	}
	{returns: Number of items currently available in the object pool.}
}
$*/
/*$
{function:
	{name: RvObjPoolTotalPages}
	{superpackage: ObjPool}