Memory management. More...

#include <ptypes.h>
#include <pmacros.h>
#include <perror.h>

Data Structures
struct	PMemVTable_
	Memory management table. More...

Typedefs
typedef struct PMemVTable_	PMemVTable
	Memory management table.

Functions
P_LIB_API ppointer	p_malloc (psize n_bytes)
	Allocates a memory block for the specified number of bytes.

P_LIB_API ppointer	p_malloc0 (psize n_bytes)
	Allocates a memory block for the specified number of bytes and fills it with zeros.

P_LIB_API ppointer	p_realloc (ppointer mem, psize n_bytes)
	Changes the memory block size.

P_LIB_API void	p_free (ppointer mem)
	Frees a memory block by its pointer.

P_LIB_API pboolean	p_mem_set_vtable (const PMemVTable *table)
	Sets custom memory management routines.

P_LIB_API void	p_mem_restore_vtable (void)
	Restores system memory management routines.

P_LIB_API ppointer	p_mem_mmap (psize n_bytes, PError **error)
	Gets a memory mapped block from the system.

P_LIB_API pboolean	p_mem_munmap (ppointer mem, psize n_bytes, PError **error)
	Unmaps memory back to the system.

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:

automatical checking of all input parameters for the NULL values;
ability to use a custom memory allocator. You can also mix these two families of calls, but it is not recommended.

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.

Definition in file pmem.h.

Function Documentation

◆ p_free()

P_LIB_API void p_free ( ppointer mem )

Frees a memory block by its pointer.

Parameters

mem	Pointer 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_bytes Size 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_bytes Size 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_bytes	Size of the memory block in bytes.
[out]	error	Error 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

	mem	Pointer to a memory block previously allocated using the p_mem_mmap() call.
	n_bytes	Size of the memory block in bytes.
[out]	error	Error 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

table Table 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

mem	Pointer to the memory block.
n_bytes	New 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

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation

◆ p_free()

◆ p_malloc()

◆ p_malloc0()

◆ p_mem_mmap()

◆ p_mem_munmap()

◆ p_mem_restore_vtable()

◆ p_mem_set_vtable()

◆ p_realloc()