framework/c/inc/le_mem.h File Reference

Go to the source code of this file.

Data Structures
struct	le_mem_PoolStats_t
Typedefs
typedef struct le_mem_Pool *	le_mem_PoolRef_t
typedef void(*	le_mem_Destructor_t )(void *objPtr)
Functions
le_mem_PoolRef_t	le_mem_CreatePool (const char *name, size_t objSize)
le_mem_PoolRef_t	le_mem_ExpandPool (le_mem_PoolRef_t pool, size_t numObjects)
void *	le_mem_TryAlloc (le_mem_PoolRef_t pool)
void *	le_mem_AssertAlloc (le_mem_PoolRef_t pool)
void *	le_mem_ForceAlloc (le_mem_PoolRef_t pool)
void	le_mem_SetNumObjsToForce (le_mem_PoolRef_t pool, size_t numObjects)
void	le_mem_Release (void *objPtr)
void	le_mem_AddRef (void *objPtr)
void	le_mem_SetDestructor (le_mem_PoolRef_t pool, le_mem_Destructor_t destructor)
void	le_mem_GetStats (le_mem_PoolRef_t pool, le_mem_PoolStats_t *statsPtr)
void	le_mem_ResetStats (le_mem_PoolRef_t pool)
size_t	le_mem_GetTotalNumObjs (le_mem_PoolRef_t pool)
size_t	le_mem_GetObjectSize (le_mem_PoolRef_t pool)
le_mem_PoolRef_t	le_mem_FindPool (const char *name)
le_mem_PoolRef_t	le_mem_CreateSubPool (le_mem_PoolRef_t superPool, const char *name, size_t numObjects)
void	le_mem_DeleteSubPool (le_mem_PoolRef_t subPool)

---

Detailed Description

Legato Dynamic Memory Allocation API include file.

Copyright (C) Sierra Wireless, Inc. 2012. All rights reserved. Use of this work is subject to license.

---

Typedef Documentation

typedef void(* le_mem_Destructor_t)(void *objPtr)

Prototype for destructor functions.

Parameters:

objPtr

Pointer to the object where reference count has reached zero. After the destructor returns this object's memory will be released back into the pool (and this pointer will become invalid).

Returns:

Nothing.

See Destructors for more information.

typedef struct le_mem_Pool* le_mem_PoolRef_t

Objects of this type are used to refer to a memory pool created using either le_mem_CreatePool() or le_mem_CreateSubPool().

---

Function Documentation

void le_mem_AddRef

(

void *

objPtr

)

Increments the reference count on an object by 1.

See Reference Counting for more information.

Returns:

Nothing.

Parameters:

[in]

objPtr

Pointer to the object.

void* le_mem_AssertAlloc

(

le_mem_PoolRef_t

pool

)

Allocates an object from a pool or logs a fatal error and terminates the process if the pool doesn't have any free objects to allocate.

Returns:

Pointer to the allocated object.

Note:

On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.

Parameters:

[in]

pool

Pool from which the object is to be allocated.

le_mem_PoolRef_t le_mem_CreatePool	(	const char *	name,
		size_t	objSize
	)

Creates an empty memory pool.

Returns:

Reference to the memory pool object.

Note:

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

Parameters:

[in]	name	Name of the pool (will be copied into the Pool).
[in]	objSize	Size of the individual objects to be allocated from this pool (in bytes), e.g., sizeof(MyObject_t).

le_mem_PoolRef_t le_mem_CreateSubPool	(	le_mem_PoolRef_t	superPool,
		const char *	name,
		size_t	numObjects
	)

Creates a sub-pool. You can't create sub-pools of sub-pools so do not attempt to pass a sub-pool in the superPool parameter.

See Sub-Pools for more information.

Returns:

Reference to the sub-pool.

Parameters:

[in]	superPool	Super-pool.
[in]	name	Name of the sub-pool (will be copied into the sub-pool).
[in]	numObjects	Number of objects to take from the super-pool.

void le_mem_DeleteSubPool

(

le_mem_PoolRef_t

subPool

)

Deletes a sub-pool.

See Sub-Pools for more information.

Returns:

Nothing.

Parameters:

[in]

subPool

Sub-pool to be deleted.

le_mem_PoolRef_t le_mem_ExpandPool	(	le_mem_PoolRef_t	pool,
		size_t	numObjects
	)

Expands the size of a memory pool.

Returns:

Reference to the memory pool object (the same value passed into it).

Note:

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

Parameters:

[in]	pool	Pool to be expanded.
[in]	numObjects	Number of objects to add to the pool.

le_mem_PoolRef_t le_mem_FindPool

(

const char *

name

)

Finds a pool based on the pool's name.

Returns:

Reference to the pool, or NULL if the pool doesn't exist.

Parameters:

[in]

name

Name of the pool.

void* le_mem_ForceAlloc

(

le_mem_PoolRef_t

pool

)

Allocates an object from a pool or logs a warning and expands the pool if the pool doesn't have any free objects to allocate.

Returns:

Pointer to the allocated object.

Note:

On failure, the process exits, so you don't have to worry about checking the returned pointer for validity.

Parameters:

[in]

pool

Pool from which the object is to be allocated.

size_t le_mem_GetObjectSize

(

le_mem_PoolRef_t

pool

)

Fetches the size of the objects in a specified pool (in bytes).

Returns:

Object size, in bytes.

Parameters:

[in]

pool

Pool where object size is to be fetched.

void le_mem_GetStats	(	le_mem_PoolRef_t	pool,
		le_mem_PoolStats_t *	statsPtr
	)

Fetches the statistics for a specified pool.

Returns:

Nothing. Uses output parameter instead.

Parameters:

[in]	pool	Pool where stats are to be fetched.
[out]	statsPtr	Pointer to where the stats will be stored.

size_t le_mem_GetTotalNumObjs

(

le_mem_PoolRef_t

pool

)

Fetches the number of objects a specified pool can hold (this includes both the number of free and in-use objects).

Returns:

Total number of objects.

Parameters:

[in]

pool

Pool where number of objects is to be fetched.

void le_mem_Release

(

void *

objPtr

)

Releases an object. If the object's reference count has reached zero, it will be destructed and its memory will be put back into the pool for later reuse.

Returns:

Nothing.

Warning:

• Don't EVER access an object after releasing it. It might not exist anymore.
• If the object has a destructor accessing a data structure shared by multiple threads, ensure you hold the mutex (or take other measures to prevent races) before releasing the object.

Parameters:

[in]

objPtr

Pointer to the object to be released.

void le_mem_ResetStats

(

le_mem_PoolRef_t

pool

)

Resets the statistics for a specified pool.

Returns:

Nothing.

Parameters:

[in]

pool

Pool where stats are to be reset.

void le_mem_SetDestructor	(	le_mem_PoolRef_t	pool,
		le_mem_Destructor_t	destructor
	)

Sets the destructor function for a specified pool.

See Destructors for more information.

Returns:

Nothing.

Parameters:

[in]	pool	The pool.
[in]	destructor	Destructor function.

void le_mem_SetNumObjsToForce	(	le_mem_PoolRef_t	pool,
		size_t	numObjects
	)

Sets the number of objects that are added when le_mem_ForceAlloc expands the pool.

Returns:

Nothing.

Note:

The default value is one.

Parameters:

[in]	pool	Pool to set the number of objects for.
[in]	numObjects	Number of objects that is added when le_mem_ForceAlloc expands the pool.

void* le_mem_TryAlloc

(

le_mem_PoolRef_t

pool

)

Attempts to allocate an object from a pool.

Returns:

Pointer to the allocated object, or NULL if the pool doesn't have any free objects to allocate.

Parameters:

[in]

pool

Pool from which the object is to be allocated.