Low-level Memory Management
=============================


Yimmo memory management API.

This file defines a set of convenience macros used to wrap common memory
allocation/deallocation functions. Which functions are actually invoked are
dependent on configuration options.

.. contents:: Contents
 :local:
 :depth: 3



Allocator Macros
------------------



.. c:macro:: YMO_ALLOC(n)

 Allocates n bytes, aligned to at least sizeof(void*).

 :param n: number of bytes to allocate.



.. c:macro:: YMO_ALLOC0(n)

 Allocates n bytes, zeroed and aligned to at least sizeof(void*).

 :param n: number of bytes to allocate.



.. c:macro:: YMO_FREE(p)

 free n bytes of memory pointed to by p.

 :param n: size of the block to free, as passed to :c:macro:`YMO_ALLOC`
 :param p: a void* to the memory being freed

 **Example:**

 ```C
 size_t n = ...;
 char* p = YMO_ALLOC(n);
 do_stuff(p);
 YMO_FREE(p);
 ```




.. c:macro:: YMO_NEW(t)

 Allocate sufficient space to accommodate an object of type t.

 :param t: a type name for which we need to allocate space

 **Example:**

 ```C
 // Allocates sizeof(my_type_t) bytes:
 my_type_t* my_obj = YMO_NEW(my_type_t);
 ```




.. c:macro:: YMO_NEW0(t)

 Allocate and zero sufficient space for an object of type t.

 :param t: a type name for which we need to allocate space

 **Example:**

 ```C
 // Allocates sizeof(my_type_t) bytes:
 my_type_t* my_obj = YMO_NEW0(my_type_t);
 ```




.. c:macro:: YMO_DELETE(t, p)

 Deallocate memory allocated via :c:macro:`YMO_NEW` or :c:macro:`YMO_NEW0`.

 :param t: the type that was allocated via :c:macro:`YMO_NEW` or :c:macro:`YMO_NEW0`
 :param p: a void* to the object being freed

 **Example:**

 ```C
 // Allocates sizeof(my_type_t) bytes:
 my_type_t* my_obj = YMO_NEW0(my_type_t);
 do_stuff(my_obj);
 YMO_DELETE(my_type_t, my_obj);
 ```




Customization
---------------

The allocation macros above are all wrappers for one of the following three
functions: :c:func:`ymo_malloc`, :c:func:`ymo_calloc`, :c:func:`ymo_free`.

(By default, these are either aliases or wrappers for ``malloc``, ``calloc``,
and ``free``).

On platforms that support ``weakref``, ``weak, alias``, or ``weak``, these
are defined to be *weak* symbols. This allows the core memory routines to
be overridden by user-supplied routines by providing strong symbols at
link time.

You can check to see if this mechanism is available using the
:c:macro:`YMO_ALLOC_LT_OVERRIDE` macro.

**Example**:

.. code-block:: c

   #include "ymo_alloc.h"

   #if YMO_ALLOC_LT_OVERRIDE

   // Here's a silly ymo_malloc override which
   // just prints the number of bytes allocated:
   void* ymo_malloc(size_t n)
   {
       fprintf(stderr, "Allocating %zu bytes!\n", n);
       return malloc(n);
   }
   #endif


Default Allocator Functions
...........................

.. c:macro:: YMO_ALLOC_LT_OVERRIDE

   Set to ``1`` if link-time memory customization is possible; ``0``, otherwise.

.. c:function:: void* ymo_malloc(size_t n)

   Wrapper/alias for ``malloc``.

.. c:function:: void* ymo_calloc(size_t c, size_t n)

   Wrapper/alias for ``calloc``.

.. c:function:: void ymo_free(void* p)

   Wrapper/alias for ``free``.


Disabling Link-Time Overrides
.............................

The link-time override methods can be disabled at configure-time, even on
platforms which support them, by setting any of the following flags to ``0``:

- ``YMO_ALLOC_ALLOW_WEAKREF``
- ``YMO_ALLOC_ALLOW_WEAK``
- ``YMO_ALLOC_ALLOW_ALIAS``

To disable link-time overrides entirely, for example, you would do the
following:

.. code-block:: bash

   ../configure \
       YMO_ALLOC_ALLOW_WEAKREF=0 \
       YMO_ALLOC_ALLOW_WEAK=0 \
       YMO_ALLOC_ALLOW_ALIAS=0


Customizing at Compile-Time
...........................

On platforms which lack support for the linking mechanisms above, it is
possible to override these functions at compile-time by defining the
symbols via the preprocessor, e.g.:

.. code-block:: bash

   ../configure CFLAGS="-Dymo_malloc=my_custom_malloc"