rvmemory.h

基于h323协议的软phone

/***********************************************************************
Filename   : rvmemory.h
Description: rvmemory 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: Memory}
	{superpackage: CCore}
	{include: rvmemory.h}
	{description:	
		{p: This module provides memory management functions with plug-in
			drivers to supports various memory management schemes.}
	}
}
$*/
#ifndef RV_MEMORY_H
#define RV_MEMORY_H

#include "rvccore.h"
#include "rvobjlist.h"

#if (RV_MEMORY_DEBUGINFO == 1)
#include "rvlock.h"
#endif

/* Forward declarations so it can be used by memory driver headers */
typedef struct RvMemory_s RvMemory;
typedef struct RvMemoryInfo_s RvMemoryInfo;
typedef struct RvMemoryDriverFuncs_s RvMemoryDriverFuncs; /* Currently used internally only. */

/* Memory driver header includes. Driver headers should insure that */
/* their headers are completely read in before this header is parsed. */
#include "rvosmem.h"
#include "rvpoolmem.h"

/* Error checks to make sure configuration has been done properly */
#if !defined(RV_MEMORY_TYPE) || ((RV_MEMORY_TYPE != RV_MEMORY_STANDARD))
#error RV_MEMORY_TYPE not set properly
#endif

#if !defined(RV_MEMORY_MAX_NAMESIZE) || (RV_MEMORY_MAX_NAMESIZE < 1)
#error RV_MEMORY_MAX_NAMESIZE not set properly
#endif

#if !defined(RV_MEMORY_KEEPSTATS) || (RV_MEMORY_KEEPSTATS < 0) || (RV_MEMORY_KEEPSTATS > 1)
#error RV_MEMORY_KEEPSTATS not set properly
#endif

#if !defined(RV_MEMORY_DEBUGINFO) || (RV_MEMORY_DEBUGINFO < 0) || (RV_MEMORY_DEBUGINFO > 1)
#error RV_MEMORY_DEBUGINFO not set properly
#endif

#if !defined(RV_MEMORY_DEBUGCHECK) || (RV_MEMORY_DEBUGCHECK < 0) || (RV_MEMORY_DEBUGCHECK > 1)
#error RV_MEMORY_DEBUGCHECK not set properly
#endif
/* End of configuration error checks */

/* Module specific error codes (-512..-1023). See rverror.h for more details */
#define RV_MEMORY_ERROR_DRIVERFAILED -512 /* requested driver not available due to failure */
#define RV_MEMORY_ERROR_OVERRUN -513 /* memory allocation boundry has been overrun */

/* *************IMPORTANT*******************                                           */
/* To add a new driver (other than writing and testing the module itself):                                                                */
/*    1. add header file to include list at the top of this file                       */
/*    2. Increment RV_MEMORY_NUMDRIVERS                                                */
/*    3. Add a RV_MEMORY_DRIVER_XXX constant to the ID list                            */
/*    4. Add a new type to the driverData union in RvMemory_s structure                */
/*    5. In the rvmemory.c file, add the driver functions to the RvMemoryDrivers array */
/*    6. In the rvmemory.c file, add a new item to the switch in RvMemoryConstruct     */
/* *****************************************                                           */

/* Number of memory drivers */
#define RV_MEMORY_NUMDRIVERS 2

/* Memory Driver ID numbers */
#define RV_MEMORY_DRIVER_OSMEM 0   /* ID 0 is used for the default region */
#define RV_MEMORY_DRIVER_POOLMEM 1

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

/*$
{callback:
	{name:	  RvMemoryFunc}	
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Out of memory callback. This callback is called when a memory region
			can not allocate the memory needed for a memory allocation.}
	}
	{proto: RvStatus RvMemoryFunc(RvSize_t n);}
	{params:
		{param: {n: n} {d: The number of bytes needed. }}
	}
	{returns:	Return RV_OK if allocation attempt should be tried again. Returning
				an any error code will abort the memory allocation and return an
				error to the caller.}
}
$*/
typedef RvStatus (*RvMemoryFunc)(RvSize_t n);

/*$
{type:
	{name: RvMemoryInfo}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:	
		{p: A structure containing information about a memory region. This structure is
			returned by the RvMemoryInfo command. Not all fields may be filled in (will
			show a value of 0) if the OS doesn't support it or the RV_MEMORY_STATISTICS
			option is not enabled.}
	}
	{attributes scope="public":
		{attribute: {t: RvChar *}  {n: name}                   {d: name of memory region}}
		{attribute: {t: RvInt }    {n: drivernum}              {d: driver ID of driver used by the region}}
		{attribute: {t: RvSize_t } {n: bytes_requested_byuser} {d: # of bytes used, per user request}}
		{attribute: {t: RvSize_t } {n: bytes_requested_bymem}  {d: # of bytes used, including Memory layer overhead}}
		{attribute: {t: RvSize_t } {n: bytes_requested_total}  {d: # of bytes used, including all per allocation overhead}}
		{attribute: {t: RvSize_t } {n: bytes_total_inuse}      {d: Total number of bytes in use}}
		{attribute: {t: RvSize_t } {n: allocs_requested}       {d: number of actual allocation still in use}}
		{attribute: {t: RvSize_t } {n: bytes_free_now}         {d: # of bytes imediately available without asking for more}}
		{attribute: {t: RvSize_t } {n: bytes_free_total}       {d: Total number of bytes available}}
		{attribute: {t: RvSize_t } {n: allocs_free_now}        {d: # of actual allocations available}}
		{attribute: {t: RvSize_t } {n: allocs_free_total}      {d: Total number of acutual allocations available}}
	}
}
$*/
/* Most field are filled in by the driver itself. The actual typedef */
/* is above for forward declarations. */
struct RvMemoryInfo_s {
	RvChar name[RV_MEMORY_MAX_NAMESIZE]; /* name of region (filled in by rvmemory) */
	RvInt drivernum;                     /* driver number of region (filled in by rvmemory) */
	RvSize_t bytes_requested_byuser;     /* # of bytes used, per user request */
	RvSize_t bytes_requested_bymem;      /* # of bytes used, including rvmemory layer overhead */
	RvSize_t bytes_requested_total;      /* # of bytes used, including all per allocation overhead */
	RvSize_t bytes_total_inuse;          /* Total number of bytes in use */
	RvSize_t allocs_requested;           /* number of actual allocations still in use */
	RvSize_t bytes_free_now;             /* # of bytes immediately available without asking for more */
	RvSize_t bytes_free_total;           /* Total number of bytes available */
	RvSize_t allocs_free_now;            /* # of actual allocations available */
	RvSize_t allocs_free_total;          /* Total number of actual allocations available */
};

/*$
{type:
	{name: RvMemory}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:	
		{p: A memory region object.}
	}
}
$*/
/* Actual typedef is above for forward declarations. */
struct RvMemory_s {
	RvInt drivernum;                      /* driver number */
	RvChar name[RV_MEMORY_MAX_NAMESIZE];  /* Name of region */
	RvMemoryDriverFuncs *drivercalls;     /* pointer to driver functions (faster than indexing) */
	RvObjListElement listElem;            /* used to maintain list of current regions */
	void *start;                          /* starting address of region (if needed) */
	RvSize_t size;                        /* size of region (if needed) */
	RvMemory *moremem;                    /* region to request addional memory from (if needed) */
	RvMemoryFunc nomem;                   /* function to call when no additional memory available */
	void *driverRegion;                   /* pointer to driver specific region data in union (for speed) */
	union {                               /* driver specific data, MUST have one entry for each driver */
		RvOsMemData osMemData;
		RvPoolMemData poolMemData;
	} driverData;
#if (RV_MEMORY_DEBUGINFO == 1)
	RvObjList alloclist;                  /* List of blocks allocated from region */
	RvLock listlock;                      /* Lock use for alloclist. */
#endif
};

/* Prototypes and macros: See documentation blocks below for details. */
RvStatus RvMemoryInit(void);
RvStatus RvMemoryEnd(void);
RvStatus RvMemoryConstruct(RvMemory *region, RvInt drivernum, RvChar *name, void *start, RvSize_t size, RvMemory *moremem, RvMemoryFunc nomem, void *attr);
RvStatus RvMemoryDestruct(RvMemory *region);
RVCOREAPI RvStatus RVCALLCONV RvMemoryFree(void *ptr);
RVCOREAPI RvStatus RVCALLCONV RvMemoryGetInfo(RvMemory *reqregion, RvMemoryInfo *meminfo);
RvStatus RvMemorySetDefaultMemCB(RvMemoryFunc func);
RvStatus RvMemoryGetDefaultMemCB(RvMemoryFunc *func);
#if (RV_MEMORY_DEBUGINFO != 1)
RVCOREAPI RvStatus RVCALLCONV RvMemoryAlloc(RvMemory *reqregion, void **resultptr, RvSize_t size);
#else
/* Special Alloc for debugging */
#define RvMemoryAlloc(_r, _p, _s) RvMemoryAllocDbg((_r), (_p), (_s), __LINE__, __FILE__)
RVCOREAPI RvStatus RVCALLCONV RvMemoryAllocDbg(RvMemory *reqregion, void **resultptr, RvSize_t size, RvInt line, RvChar *filename);
#endif

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

#if defined(__cplusplus)
}
#endif 

/* Function Documentation */
/*$
{function scope="protected":
	{name: RvMemoryInit}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Initializes the Memory module. Must be called once (and
			only once) before any other functions in the module are called.
			A default region is created with the default driver.}
	}
	{proto: RvStatus RvMemoryInit(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
	{name: RvMemoryEnd}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Shuts down the Memory module. Must be called once (and
			only once) when no further calls to this module will be made.
			The default region is destroyed.}
	}
	{proto: RvStatus RvMemoryEnd(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMemoryConstruct}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Creates a memory region. Different drivers may interpret some of the parameters
			in different ways. Refer to those drivers for further information.}
	}
	{proto: RvStatus RvMemoryConstruct(RvMemory *region, RvInt drivernum, RvChar *name, void *start, RvSize_t size, RvMemory *moremem, RvMemoryFunc nomem, void *attr);}
	{params:
		{param: {n: region} {d: Pointer to object where region information will be stored.}}
		{param: {n: drivernum} {d: Driver ID of memory allocation driver to use. See rvmemory.h for current list.}}
		{param: {n: name} {d: Pointer to string name to use for this region (a copy will be made).}}
		{param: {n: start} {d: Starting address of region (not used by all drivers).}}
		{param: {n: size} {d: Size to use for region (driver specific).}}
		{param: {n: moremem} {d: Memory region to get additional memory from (not used by all drivers).}}
		{param: {n: nomem} {d: Callback function that will be called if no more memory can be aquired (NULL is allowed).}}
		{param: {n: attr} {d: Driver specific parameters.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:  A copy of the name string passed in is made. The maximum size of the
				the string is RV_MEMORY_MAX_NAMESIZE and names that are too long
				will be truncated.}
	}
}
$*/
/*$
{function:
	{name: RvMemoryDestruct}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Destroys a memory region.}
	}
	{proto: RvStatus RvMemoryDestruct(RvMemory *region);}
	{params:
		{param: {n: region} {d: Pointer to the region object to be destroyed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:  Some drivers allow destroying regions with outstanding allocations
				and some do not.}
	}
}
$*/
/*$
{function:
	{name: RvMemoryAlloc}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Allocates memory from a region.}
	}
	{proto: RvStatus RvMemoryAlloc(RvMemory *reqregion, void **resultptr, RvSize_t size);}
	{params:
		{param: {n: reqregion} {d: Pointer to the region to request the memory from (NULL = default region).}}
		{param: {n: resultptr} {d: Pointer to where the resulting memory pointer will be stored.}}
		{param: {n: size} {d: Number of bytes of memory needed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMemoryFree}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Returns allocated memory back to region it came from.}
	}
	{proto: RvStatus RvMemoryFree(void *ptr);}
	{params:
		{param: {n: ptr} {d: Pointer to allocated memory. Must be the same pointer returned by rvMemoryAlloc.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMemoryGetInfo}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Returns statistics about a memory region.}
	}
	{proto: RvStatus RvMemoryGetInfo(RvMemory *reqregion, RvMemoryInfo *meminfo);}
	{params:
		{param: {n: reqregion} {d: Pointer to the region to request information from (NULL = default region).}}
		{param: {n: memory} {d: Pointer to a structure which will be filled in with the statistics.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMemorySetDefaultMemCB}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Sets an out of memory callback for the default region.}
	}
	{proto: RvStatus RvMemorySetDefaultMemCB(RvMemoryFunc func);}
	{params:
		{param: {n: func} {d: Out of memory callback (NULL = none).}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMemoryGetDefaultMemCB}
	{superpackage: Memory}
	{include: rvmemory.h}
	{description:
		{p: Gets the current out of memory callback for the default region.}
	}
	{proto: RvStatus RvMemoryGetDefaultMemCB(RvMemoryFunc *func);}
	{params:
		{param: {n: func} {d: Function pointer where the callback pointer is stored (result can be NULL).}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/

#endif