T3E Memory Pool (v0.03)

int mpnew(char *descr;)

The mpnew() function creates/initializes a new memory pool with the description pointed to by descr. If the descr is NULL then "-" is used as description. If the manager runs in a multithreading environment it assigns the thread ID to the memory pool so that only that thread can access it during its lifetime.

This function returns the memory pool ID of the allocated memory pool.

int mppush(int mpid);

The mppush() function moves the current memory pool ID to the stack and makes mpid the current one. The stack has only one element, for now.

Upon successful completion this function returns MP_ERRNO_SUCCESS. In case mpid is out of the limits of allowed memory pools IDs, it returns MP_ERRNO_MPID. And in case the memory pool corresponding to mpid is not initialized with mpnew() then the function returns MP_ERRNO_NOIN.

int mppop();

The mppop() function sets the previous Memory Pool ID moved to the stack by mppush() as the current one.

When no error, the function returns MP_ERRNO_SUCCESS. In case there was no memory pool ID stored in the stack the function returns MP_ERRNO_NOPP.

int mpget();

The mpget() function gets the current memory pool ID set by mpset() and the one which is currently used for the allocation.

This function returns the actual memory pool ID.

int mpset(int mpid);

The mpset() function tells the memory pool manager that mpid should be the active memory pool from which all further allocations are made.

Upon successful completion this function returns MP_ERRNO_SUCCESS. If the memory pool referred by mpid is not yet initialized by mpnew() then it returns MP_ERRNO_NOIN. If mpid is out the limits allowed by the library then the function returns MP_ERRNO_MPID. If the thread trying to set the memory pool is not the same one that initialized/created it with mpnew() it returns MP_ERRNO_THRD.

int mpdel(int mpid);

The mpdel() function frees all resources (memory blocks) allocated for the memory pool referrenced by mpid and initializes it, this last happens unless mpid refers to the default memory pool, which cannot be uninitialized.

On successful completion this function returns MP_ERRNO_SUCCESS. If mpid is out the limits allowed by the library then the function returns MP_ERRNO_MPID. If the thread trying to delete the memory pool is not the same one that initialized/created it with mpnew() it returns MP_ERRNO_THRD.

int mpdel_all();

The mpdel_all() function frees the resources (memory blocks) allocated for each of the memory pools and initializes each of the pools except by the default one, which is always kept initialized.

Note: This function should always be called by the main thread and only when all the other threads stopped using any of the memory pools. Doing otherwise may cause unexpected behaviour.

This function always returns MP_ERRNO_SUCCESS.

int mpclr(int mpid);

The mpclr() function resets to zero all the memory usage pointers used by the memory pool referred by mpid making immediate availability of the memory blocks allocated for that pool.

On successful completion this function returns MP_ERRNO_SUCCESS. If mpid is out the limits allowed by the library then the function returns MP_ERRNO_MPID. If the thread trying to clear the memory pool is not the same one that initialized/created it using mpnew() it returns MP_ERRNO_THRD.

void mpprn();

The mpprn() function prints on the screen the different information of each of the created/initialized memory pools. For the display it uses the output set by the function mptrc_set_fn() or the default standard output if no other output was set.

The information showed in the statistics are the memory pool ID, the memory pool name, the number of memory blocks assigned to that pool, the total memory size allocated for all the blocks, the total free memory among all memory pools and the percentages of used and free memory.

Example of the output:

==============================================================================
MPID Descr           Blocks   Size       Used       %        Free       %
------------------------------------------------------------------------------
   0 Default         1        250.0Kb    20.0b      %0.01    250.0Kb    %99.99 
   1 Memory Pool 1   1        250.0Kb    156.0b     %0.06    249.9Kb    %99.94 
   2 Memory Pool 2   1        250.0Kb    0.0b       %0.00    250.0Kb    %100.00
------------------------------------------------------------------------------
Total                3        750.0Kb    176.0b     %0.02    749.8Kb    %99.98 
==============================================================================

This function doesn't returns any value.

int mpdmp(char *filename);

The function mpdmp() dumps to the file pointed by filename the content of the memory allocated for each of memory blocks assigned to the initialized memory pools. The filename can contain the file path, if no path is specified the file is created in the current directory.

The function will try to skip dumping zero bytes blocks and it will replace them with the string "(skipped zero bytes...)"

The dump is split by memory pool, showing the memory pool ID and its name, and by its memory blocks, showing in the title the sequence of the block number, its size and its range of memory address.

Upon successfully termination this function returns MP_ERRNO_SUCCESS. If the function is called with filename equal NULL then it returns MP_ERRNO_PARM. In case there is any error delivered by the system function fopen() when opening the file, the function returns MP_ERRNO_SYSE, the mperrno variable is also set with the same value in order to get the corresponding error message with mpstrerror().

Example of the output dumped to filename:

==================================================================================
Memory pool dump (Report of memory used)                      2014/10/12 15:19:32
----------------------------------------------------------------------------------
Memory pool: Default (ID: 0)
----------------------------------------------------------------------------------
----------------------------------------------------------------------------------
Block number: 1 size: 9.8Kb from: 0x95f89c0 to 0x95fb10f
----------------------------------------------------------------------------------
0x000000095f89c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
(skipped zero bytes...)
0x000000095fb100: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
----------------------------------------------------------------------------------

void mpset_memlim(size_t size);

The mpset_memlim() function allows setting the maximum memory limit in bytes that can be allocated by all memory pools at the same time. Any attempt of allocation above this limit causes an error. The default maximum memory limit set automatically by the manager during startup is of 3 GB for 32 bits platforms and 5 GB for 64 bits platforms.

This function does not returns any value.

size_t mpget_memlim();

The mpget_memlim() function delivers the current maximum memory limit of the memory pool manager in bytes.

void mpset_blksz(size_t size);

The function mpset_blksz() allows setting the size in bytes of the blocks that are allocated for each memory pool. The default size used by the manager is of 250 KB.

This function does not returns any value.

size_t mpget_blksz();

The mpget_blksz() function returns the size of the memory blocks used by the manager for allocating memory from the heap for each of the memory pools.

void *mpmalloc(size_t size);
void mpfree(void *ptr);
void *mpcalloc(size_t nelem, size_t size);
void *mprealloc(void *ptr, size_t size);
void *mpmemalign(size_t alignment, size_t size);

void *mpmalloc_mpid(size_t size, int mpid);
void *mpcalloc_mpid(size_t nelem, size_t size, int mpid);
void mpfree_mpid(void *ptr, int mpid);
void *mprealloc_mpid(void *ptr, size_t size, int mpid);
void *mpmemalign_mpid(size_t alignment, size_t size, int mpid);

The mpmalloc() function is analog to the malloc() function and allocates size bytes and returns a pointer to the allocated memory within the active memory pool. The memory is not initialized. If size is 0, then mpmalloc() returns anyway unique pointer.

The mpfree() function is actually a dummy function that doesn't do anything. It exists only as analogy to the free() function. Due to the current architecture of the memory pool manager each chunk of memory requested to the manager is taken sequentially from the pool and its space is not reused until the whole pool is clear or freed until the pool is deleted.

The mpcalloc() function is analog to the calloc() function and allocates memory for an array of nelem elements of size bytes each and returns a pointer to the allocated memory within the active memory pool.
The memory is set to zero. If nelem or size is 0, then mpcalloc() returns anyway unique pointer.

The mprealloc() function is analog to the realloc() function and changes the size of the memory block pointed to by ptr to size bytes. The contents will be unchanged in the range from the start of the region up to the minimum of the old and new sizes. If the new size is larger than the old size, the added memory will not be initialized. If ptr is NULL, then the call is equivalent to mpmalloc(size), for all values of size; if size is equal to zero, and ptr is not NULL, then anyway a pointer is delivered. Unless ptr is NULL, it must have been returned by an earlier call to mpmalloc(), mpcalloc() or mprealloc().

The function mpmemalign() is analog to the memalign() function and allocates size bytes and returns a pointer to the allocated memory within the current memory pool. The memory address will be multiple of alignment, which must be a power of two and a multiple of sizeof(void *). If size is 0 then mpmemalign returns anyway an unique pointer.

The functions mpmalloc_mpid(), mpfree_mpid(), mpcalloc_mpid(), mprealloc_mpid() and mpmemalign_mpid() are equivalent to the functions mpmalloc(), mpfree(), mpcalloc(), mprealloc() and mpmemalign() respectively, except that they are called additionally with mpid, which indicates explicitely from which particular memory pool that chunk of memory will be taken, no matter what the currently active memory pool is.

char *mpstrdup(const char *s1);
char *mpstrdup_mpid(const char *s1, int mpid);

The mpstrdup() function is analog to the strdup() function and returns a pointer to the new string which is a duplicate of the string s1. Memory for the new string is obtained with mpmalloc() from the currently active memory pool.

The mpstrdup_mpid() function equivalent to the mpstrdup() function, except that it is called additionally with mpid, which indicates explicitlyfrom which particular memory pool that chunk of memory will be taken, no matter what the currently active memory pool is.

int mpasprintf(char **strp, const char *fmt, ...);
int mpasprintf_mpid(char **strp, int mpid, const char *fmt, ...);

The mpasprintf() function is analog to the asprintf() function and allocates a string large enough to hold the output including the terminating null byte ('\0'), and returns a pointer to it via the first argument.

The mpasprintf_mpid() function equivalent to the mpasprintf() function, except that it is called additionally with mpid, which indicates explicitely from which particular memory pool that chunk of memory will be taken, no matter what the currently active memory pool is.

char *mpstrerror();

The mpstrerror() function is analog to the strerror() function and returns a pointer to a string that describes the error code set by any of the memory pool manager functions an error is encountered. (For example if the code set by any function is MP_ERRNO_NOMM, the returned description will be "Out of memory".) This string is read-only and may not be modified. The mpstrerror() is thread safe. The string always includes a terminating null byte ('\0').

The mpstrerror() function returns the appropriate error description string, or and "Error number not recognized" message if the error number is unknown.

In case the error is due to a system error, the result of the function strerror(errno) is delivered.

The "mp.h" header file defines the internal integer variable mperrno, analog to errno and which is set by memory pool manager functions calls in the event of an error to indicate what went wrong. Its value is significant only when the return value of the call indicates an error (i.e. a negative value or NULL); a function that succeeds is allowed to change mperrno.

mperrno is thread-local; setting it in one thread does not affect its value in any other thread.

Below is a list of the symbolic error names that are defined for this library.

int mptrc_set_fn(int (*function)(FILE *fd, char *fmt, va_list ap));

The mptrc_set_fn() function allows setting a user defined function to control the format in which the functions mpprn() and mpdmp() display their output. For example the user has a log file with a certain format, say with process ID and timestamp. Then a customized function can be implemented so mpprn() also writes the process ID and the timestamp when showing the memory pool statics.

A way of implementation is as following example:

int mytrc(FILE *fd, char *fmt, va_list ap)
{
   char line[128] = "";

   if (fd == stdout)
   {
       vsnprintf(line, sizeof(line), fmt, ap);
       printf("         %s\n", line);
   }
   else
   {
       vfprintf(fd, fmt, ap);
       fprintf(fd, "\n");
   }
   return 0;
}

int main()
{
   mptrc_set_fn(&mytrc);