RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Manager of fixed-sized memory block

Files

file  rkhmp.h
 Platform - independent interface for supporting fixed - size memory blocks facility.
 

Data Structures

struct  RKH_MP_T
 Defines the data structure used to memory block pool facility. More...
 

Functions

void rkh_mp_init (RKH_MP_T *mp, void *sstart, rui16_t ssize, RKH_MPBS_T bsize)
 Initializes the previously allocated memory pool data strcuture RKH_MP_T. More...
 
void * rkh_mp_get (RKH_MP_T *mp)
 Get a memory block from one of the previously allocated memory pool. More...
 
void rkh_mp_put (RKH_MP_T *mp, void *blk)
 When the application is done with the memory block, it must be returned to the appropiate memory pool. The block must be allocated from the same memory pool to which it is returned. More...
 
RKH_MPBS_T rkh_mp_get_bsize (RKH_MP_T *mp)
 Retrieves the size of memory block in bytes. More...
 
RKH_MPNB_T rkh_mp_get_nfree (RKH_MP_T *mp)
 Retrieves the current number of free memory blocks in the pool. More...
 
RKH_MPNB_T rkh_mp_get_low_wmark (RKH_MP_T *mp)
 Retrieves the lowest number of free blocks ever present in the pool. This number provides valuable empirical data for proper sizing of the memory pool. More...
 
void rkh_mp_get_info (RKH_MP_T *mp, RKH_MPI_T *mpi)
 Retrieves performance information for a particular memory pool. More...
 
void rkh_mp_clear_info (RKH_MP_T *mp)
 Clear performance information for a particular memory pool. More...
 

Detailed Description

Function Documentation

void rkh_mp_init ( RKH_MP_T mp,
void *  sstart,
rui16_t  ssize,
RKH_MPBS_T  bsize 
)

Initializes the previously allocated memory pool data strcuture RKH_MP_T.

A memory block pool is declared with the RKH_MP_T data type and is defined with the rkh_mp_init() service.

A general challenge in writing this function is portability, because storage allocation is intrinsically machine-dependent. Perhaps the trickiest aspect here is the proper and optimal alignment of the blocks within the contiguous memory buffer. In particular, the alignment of blocks must be such that every new block can be treated as a pointer to the next block [MS]. Internally, this function rounds up the block size so that it can fit an integer number of pointers. This is done to achieve proper alignment of the blocks within the pool. Due to the rounding of block size the actual capacity of the pool might be less than (pool_size/blk_size). [MS]

Check the capacity of the pool by calling the rkh_mp_get_nfree() function.

Parameters
[in]mppointer to previously allocated memory pool structure.
[in]sstartstorage start. Pointer to memory from which memory blocks are allocated.
[in]ssizestorage size. Size of the memory pool storage in bytes.
[in]bsizeblock size. This number determines the size of each memory block in the pool.
Note
See RKH_MP_T structure for more information.
void* rkh_mp_get ( RKH_MP_T mp)

Get a memory block from one of the previously allocated memory pool.

Parameters
[in]mppointer to previously allocated memory pool structure.
Returns
A pointer to a new memory block or NULL if the pool runs out of blocks.
void rkh_mp_put ( RKH_MP_T mp,
void *  blk 
)

When the application is done with the memory block, it must be returned to the appropiate memory pool. The block must be allocated from the same memory pool to which it is returned.

Parameters
[in]mppointer to previously allocated memory pool structure.
[in]blkpointer to the returned memory block.
RKH_MPBS_T rkh_mp_get_bsize ( RKH_MP_T mp)

Retrieves the size of memory block in bytes.

Parameters
[in]mppointer to previously allocated memory pool structure.
Returns
The size of memory block in bytes.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_MP_GET_BSIZE_EN.
RKH_MPNB_T rkh_mp_get_nfree ( RKH_MP_T mp)

Retrieves the current number of free memory blocks in the pool.

Parameters
[in]mppointer to previously allocated memory pool structure.
Returns
The number of free memory blocks in the pool.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_MP_GET_NFREE_EN.
RKH_MPNB_T rkh_mp_get_low_wmark ( RKH_MP_T mp)

Retrieves the lowest number of free blocks ever present in the pool. This number provides valuable empirical data for proper sizing of the memory pool.

Parameters
[in]mppointer to previously allocated memory pool structure.
Returns
Lowest number of free blocks ever present in the pool.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_MP_GET_LWM_EN.
void rkh_mp_get_info ( RKH_MP_T mp,
RKH_MPI_T mpi 
)

Retrieves performance information for a particular memory pool.

Information is available during run-time for each of the RKSYS resources. This information can be useful in determining whether the application is performing properly, as well as helping to optimize the application.

Parameters
[in]mppointer to previously allocated memory pool structure.
[in]mpipointer to the buffer into which the performance information will be copied by reference.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_MP_GET_INFO_EN.
void rkh_mp_clear_info ( RKH_MP_T mp)

Clear performance information for a particular memory pool.

Parameters
[in]mppointer to previously allocated memory pool structure.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_MP_GET_INFO_EN.