Home

Libraries

Author

Links

---

Abstract Data Type StmDpool
[Dpool: Dynamic Pools of Fixed-Sized Elements]

Collaboration diagram for Abstract Data Type StmDpool:

---

Detailed Description

StmDpool is an abstract data type for dynamic pools of fixed-sized elements.

Dpool.

A StmDpool object realizes a concepually unexhausible dynamic pool of elements of a fixed size configured during creation of the pool by stmDpoolCreate().

Out of this pool such elements can be allocated and later be given back. Valid objects of type StmDpool can be achieved only as return values of stmDpoolCreate(). Moreover, variables of type StmDpool may have the value NULL meaning invalid or undefined.

Files
file	StmDpoolAdtDoc.h
	Documentation of the abstract structure data type type StmDpool.
StmDpool Representation
An object of abstract data type StmDpool is represented as a pointer to its implementation.
typedef struct StmDpoolImpl_	StmDpoolImpl_
	Type name of implementation structure.
typedef StmDpoolImpl_ *	StmDpool
	Pointer to implementation.
typedef const StmDpoolImpl_ *	ConstStmDpool
	Pointer to constant implementation.
StmDpool Creation and Destruction
StmDpool	stmDpoolCreate (size_t elsize)
	Creation of a new StmDpool object.
void	stmDpoolDestroy (StmDpool dpool)
	Destruction of the StmDpool object dpool.
StmDpool Method Functions
int	stmDpoolElsize (StmDpool dpool)
	Return the byte length of the elements held by the StmDpool object dpool.
int	stmDpoolElcount (StmDpool dpool)
	Return the number of elements currently allocated from the StmDpool object dpool.
void *	stmDpoolAllocate (StmDpool dpool)
	Allocate an element from the StmDpool object dpool and return its address.
void	stmDpoolFree (void *buf)
	Give the pool element with address buf back to its StmDpool.

---

Typedef Documentation

typedef struct StmDpoolImpl_ StmDpoolImpl_

Type name of implementation structure.

Definition at line 60 of file StmDpoolAdtDoc.h.

typedef StmDpoolImpl_* StmDpool

Pointer to implementation.

Definition at line 63 of file StmDpoolAdtDoc.h.

typedef const StmDpoolImpl_* ConstStmDpool

Pointer to constant implementation.

Definition at line 66 of file StmDpoolAdtDoc.h.

---

Function Documentation

StmDpool stmDpoolCreate

(

size_t

elsize

)

Creation of a new StmDpool object.

Parameters:

[in]

elsize

Fixed byte size of the elements of the StmDpool object.

Effects:

The function creates a StmDpool object. This object has to be used as argument of the other StmDpool functions.

Returns:

NULL on error. Then the variable errno contains the error's cause.

The StmDpool object created on success.

See also:

stmDpoolDestroy().

void stmDpoolDestroy

(

StmDpool

dpool

)

Destruction of the StmDpool object dpool.

Parameters:

[in]

dpool

The StmDpool object to destroy.

Effects:

The function destroys the StmDpool object dpool releasing all memory allocated for it and the elements held by it. It is no error to call the function for a StmDpool object with value NULL in which case the function does nothing.

Note:

Before calling this function it may be necessary to deinitialize the elements held by dpool appropriately in order to avoid memory leaks.

See also:

stmDpoolCreate().

int stmDpoolElsize

(

StmDpool

dpool

)

Return the byte length of the elements held by the StmDpool object dpool.

Parameters:

[in]

dpool

The StmDpool object.

Returns:

-1 on error. Then the variable errno contains the error's cause.

The size in bytes of the elements held by dpool on success.

int stmDpoolElcount

(

StmDpool

dpool

)

Return the number of elements currently allocated from the StmDpool object dpool.

Parameters:

[in]

dpool

The StmDpool object.

Returns:

-1 on error. Then the variable errno contains the error's cause.

The number of elements currently allocated from dpool on success.

void* stmDpoolAllocate

(

StmDpool

dpool

)

Allocate an element from the StmDpool object dpool and return its address.

Parameters:

[in]

dpool

The StmDpool object.

Effects:

The function allocates an element of the byte size stmDpoolElsize() from dpool enlarging it if necessary.

Returns:

NULL on error. Then the variable errno contains the error's cause.

The address of the element allocated on success.

See also:

stmDpoolElsize(), stmDpoolFree().

void stmDpoolFree

(

void *

buf

)

Give the pool element with address buf back to its StmDpool.

Parameters:

[in]

buf

The address of the pool element to give back.

Requires:

buf is NULL or an address achieved by stmDpoolAllocate().

Effects:

The function gives the pool element addressed by buf back to the StmDpool object it was allocated from.

Note:

It is a severe error to call stmDpoolFree() for a non NULL address which has not been achieved by stmDpoolAllocate(). Such an error is not detected by the function and results in undefined behaviour. On the other hand it is no error to call the function for the NULL pointer.

See also:

stmDpoolAllocate().

---

© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).