Ingres CL BA
From Ingres Community Wiki
|
Ingres Compatability Library |
Contents |
Compatibility Library Specification - BA
Abstract
This is the specification of the Block Allocation (BA) facility provided by the compatibility library, providing memory allocation in blocks instead of one structure at a time.
Revision: 1.0, 2-June-2008
Document History
- Revision 1.0, 2-June-2008
- Original document
Specification
Introduction
Block Allocation provides facilities for allocating and deallocating memory units in a "block" fashion. Instead of allocating one structure at a time, a bunch of structures are allocated in one shot.
The module automatically takes care of memory alignment so that each allocated structure will be correctly aligned in memory.
Minimum and maximum values can be specified for the number of blocks to allocate. The minimum value ensures that a certain number of blocks are always kept allocated. The maximum value ensures that too many blocks are not allocated. If a block becomes free and more than the minimum are allocated, then that block will be deallocated.
Algorithm
There are separate algorithms for fixed and variable length units. When a new block is allocated, either the area is formatted as separate pieces of free fixed length memory, or it is formatted as a single piece of free variable length (VL) memory. When a piece of fixed memory is requested, the first of the free list is unchained and given to the caller. When a piece of variable memory is requested, the free chain is searched for a piece large enough to satisfy the request. If one is found, the requested piece is carved from the free area and the length is updated. The free chain is kept in address sequence for VL units, so that two separate pieces can be globbed together to form a single larger space.
Library
GL
Header File <ba.h>
The header file <ba.h> must be included before using any of the functions provided. It defines the following.
_BLADEF
struct _BLADEF
{
i4 blaUnitSize; /* Size of each memory unit */
i4 blaUnitsPerBlk; /* number of units per block */
i4 blaBlkPages; /* number of pages in a block */
i4 blaBlks; /* number of blocks allocated */
i4 blaMinBlks; /* minimum # of blocks to allocate */
i4 blaMaxBlks; /* maximum # of blocks to allocate */
i4 blaFreeUnits; /* number of free units */
i4 blaFlags; /* Shared / Variable */
LNKDEF blaHdrBlks; /* hdr of list of allocated blocks */
LNKDEF blaHdrFreeUnits; /* hdr of list of free units */
MU_SEMAPHORE blaSemaphore; /* block structure semaphore */
};
BLADEF
typedef struct _BLADEF BLADEF;
Flag Values
# define BLA_SHARED 1 /* support multiple simultaneous req */ # define BLA_VARIABLE 2 /* Variable length units */
Executable Interface
The following functions are provided.
BA_New - Define and initialize a new block allocator
Calculate a "good" number of units-per-block, ensuring that the block is page-aligned, no larger than five pages, and has the least waste of space. Initialize a new block handle and allocate the specified minimum number of blocks.
Inputs:
| unit_size | The size of memory unit that the user wants to allocate with each call to 'BA_UnitAlloc()' |
| min_blocks | The minimum # of blocks to keep allocated |
| max_blocks | The maximum # of blocks to allocate. This helps control the growth of the allocated space. |
| flags | Shared access / Variable length units |
Outputs:
| blk_header | Pointer to the block header |
Returns:
| void |
Definition:
void BA_New( /* Initialize a new block allocator */ BLADEF *blk_header, /* block allocator header */ i4 unit_size, /* size of a unit (avg. for VL units */ i4 min_blocks, /* minumum # of blocks to allocate */ i4 max_blocks, /* maximum # of blocks to allocate */ i4 flags /* Flags Shared / Variable */ );
BA_Dispose - Dispose of a Block Allocator
Dispose of a Block Allocator created from BA_New.
Inputs:
| blk_header | Pointer to the block header |
Outputs:
| none |
Returns:
| void |
Definition:
void BA_Dispose( /* Free all blocks and reset alloc. */ BLADEF *blk_header /* block allocator header */ );
BA_UnitAlloc - Allocate a fixed or variable length unit of memory
Allocate a fixed or variable length unit of memory from a block.
Inputs:
| blk_header | The block header |
| unit_size | The size of memory needed (Ignored for Fixed length units) |
Outputs:
| none |
Returns:
| PTR | Pointer to allocated memory for unit |
Definition:
PTR BA_UnitAlloc( /* Allocate a F/VL unit from a block */ BLADEF *blk_header, /* block allocator header */ i4 unit_size /* requested unit size (ignored for F) */ );
BA_UnitDealloc - Deallocate a unit of memory
Deallocate the unit of memory and add it to the Block Allocator free chain.
Inputs:
| blk_header | The block header |
| unit_addr | Address of unit to deallocate |
Outputs:
| none |
Returns:
| void |
Definition:
void BA_UnitDealloc( /* Deallocate a F/VL unit from a blk */ BLADEF *blk_header, /* block allocator header */ PTR unit_addr /* Address of unit to deallocate */ );
|
Ingres Compatability Library |
