plibsys
Classes | Typedefs | Functions
pmem.h File Reference

Memory management. More...

#include <ptypes.h>
#include <pmacros.h>
#include <perror.h>
Include dependency graph for pmem.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  PMemVTable_
 Memory management table. More...
 

Typedefs

typedef P_BEGIN_DECLS struct PMemVTable_ PMemVTable
 Memory management table. More...
 

Functions

P_LIB_API ppointer p_malloc (psize n_bytes)
 Allocates a memory block for the specified number of bytes. More...
 
P_LIB_API ppointer p_malloc0 (psize n_bytes)
 Allocates a memory block for the specified number of bytes and fills it with zeros. More...
 
P_LIB_API ppointer p_realloc (ppointer mem, psize n_bytes)
 Changes the memory block size. More...
 
P_LIB_API void p_free (ppointer mem)
 Frees a memory block by its pointer. More...
 
P_LIB_API pboolean p_mem_set_vtable (const PMemVTable *table)
 Sets custom memory management routines. More...
 
P_LIB_API void p_mem_restore_vtable (void)
 Restores system memory management routines. More...
 
P_LIB_API ppointer p_mem_mmap (psize n_bytes, PError **error)
 Gets a memory mapped block from the system. More...
 
P_LIB_API pboolean p_mem_munmap (ppointer mem, psize n_bytes, PError **error)
 Unmaps memory back to the system. More...
 

Detailed Description

Memory management.

Author
Alexander Saprykin

Usually the system routines for memory management are used: malloc(), realloc(), free() and so on. But it is highly encouraged to use a more general approach: p_malloc(), p_malloc0(), p_realloc() and p_free() family of memory management routines. It gives you several advantages:

By default p_* routines are mapped to system calls, thus only NULL-checking is additionally performed. If you want to use the custom memory allocator, then fill in PMemVTable structure and pass it to the p_mem_set_vtable(). To restore system calls back use p_mem_restore_vtable().

Be careful when using the custom memory allocator: all memory chunks allocated with the custom allocator must be freed with the same allocator. If the custom allocator was installed after the library initialization call p_libsys_init() then you must to restore the original allocator before calling p_libsys_shutdown().

Use p_mem_mmap() to allocate system memory using memory mapping and p_mem_munmap() to release the mapped memory. This type of allocated memory is not backed physically (does not consume any physical storage) by operating system. It means that every memory page within the allocated region will be committed to physical backend only when you first touch it. Until that untouched pages will be reserved for future usage. It can be useful when dealing with large memory blocks which should be filled with data on demand, i.e. custom memory allocator can request a large block first, and then it allocates chunks of memory within the block upon request.

Note
OS/2 supports non-backed memory pages allocation, but in a specific way: an exception handler to control access to uncommitted pages must be allocated on the stack of each thread before using the mapped memory. To unify the behaviour, on OS/2 all memory mapped allocations are already committed to the backing storage.

Typedef Documentation

◆ PMemVTable

Memory management table.

Function Documentation

◆ p_free()

P_LIB_API void p_free ( ppointer  mem)

Frees a memory block by its pointer.

Parameters
memPointer to the memory block to free.
Since
0.0.1

You should only call this function for the pointers which were obtained using the p_malloc(), p_malloc0() and p_realloc() routines, otherwise behavior is unpredictable.

Checks the pointer for the NULL value.

◆ p_malloc()

P_LIB_API ppointer p_malloc ( psize  n_bytes)

Allocates a memory block for the specified number of bytes.

Parameters
n_bytesSize of the memory block in bytes.
Returns
Pointer to a newly allocated memory block in case of success, NULL otherwise.
Since
0.0.1

◆ p_malloc0()

P_LIB_API ppointer p_malloc0 ( psize  n_bytes)

Allocates a memory block for the specified number of bytes and fills it with zeros.

Parameters
n_bytesSize of the memory block in bytes.
Returns
Pointer to a newly allocated memory block filled with zeros in case of success, NULL otherwise.
Since
0.0.1

◆ p_mem_mmap()

P_LIB_API ppointer p_mem_mmap ( psize  n_bytes,
PError **  error 
)

Gets a memory mapped block from the system.

Parameters
n_bytesSize of the memory block in bytes.
[out]errorError report object, NULL to ignore.
Returns
Pointer to the allocated memory block in case of success, NULL otherwise.
Since
0.0.1

Note that some systems can allocate memory only in chunks of the page size, so if n_bytes is less than the page size it will try to allocate a chunk of memory equal to the page size instead.

On most systems returned memory is mapped to the null or swap device.

Warning
On OS/2 returned memory is mapped to physical storage and can be swapped.

◆ p_mem_munmap()

P_LIB_API pboolean p_mem_munmap ( ppointer  mem,
psize  n_bytes,
PError **  error 
)

Unmaps memory back to the system.

Parameters
memPointer to a memory block previously allocated using the p_mem_mmap() call.
n_bytesSize of the memory block in bytes.
[out]errorError report object, NULL to ignore.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

◆ p_mem_restore_vtable()

P_LIB_API void p_mem_restore_vtable ( void  )

Restores system memory management routines.

Note
This call is not thread-safe.
Since
0.0.1

The following system routines are restored: malloc(), free(), realloc().

◆ p_mem_set_vtable()

P_LIB_API pboolean p_mem_set_vtable ( const PMemVTable table)

Sets custom memory management routines.

Parameters
tableTable of the memory routines to use.
Returns
TRUE if the table was accepted, FALSE otherwise.
Note
All members of table must be non-NULL.
This call is not thread-safe.
Warning
Do not forget to set the original memory management routines before calling p_libsys_shutdown() if you have used p_mem_set_vtable() after the library initialization.
Since
0.0.1

In most cases you do not need to use this function. Use it only when you know what are you doing!

◆ p_realloc()

P_LIB_API ppointer p_realloc ( ppointer  mem,
psize  n_bytes 
)

Changes the memory block size.

Parameters
memPointer to the memory block.
n_bytesNew size for mem block.
Returns
Pointer to a newlly allocated memory block in case of success (if mem is NULL then it acts like p_malloc()), NULL otherwise.
Since
0.0.1