.. default-domain:: C

mm (Memory Management)
======================

Header: udo/mm.h

Table of contents (click to go)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

======
Macros
======

=====
Enums
=====

======
Unions
======

=======
Structs
=======

1. :c:struct:`udo_mm`

=========
Functions
=========

1. :c:func:`udo_mm_alloc`
#. :c:func:`udo_mm_sub_alloc`
#. :c:func:`udo_mm_sub_alloc_get_size`
#. :c:func:`udo_mm_free`
#. :c:func:`udo_mm_destroy`

API Documentation
~~~~~~~~~~~~~~~~~

| This interface was built to force caller
| to be more consciously concern about heap
| based virtual memory management.

================
udo_mm (private)
================

.. c:struct:: udo_mm

	.. c:member::
		struct udo_log_error_struct err;
		size_t                      buff_sz;
		size_t                      data_sz;
		size_t                      ab_sz;
		size_t                      offset;

	:c:member:`err`
		| Stores information about the error that occured
		| for the given context and may later be retrieved.
		| by caller.

	:c:member:`buff_sz`
		| Full size of the ``struct`` :struct:`udo_mm` context.
		| Not all bytes in the buffer are writable.

	:c:member:`data_sz`
		| Full size of the caller writable data.

	:c:member:`ab_sz`
		| The amount of available bytes the caller
		| can still write to.

	:c:member:`offset`
 		| Buffer offset used when allocating new blocks
		| in constant time. Caller may not of used the
		| entire buffer before re-allocation. Member is
		| used to keep track of end of buffer where data
		| exist.

=========================================================================================================================================

============
udo_mm_alloc
============

.. c:function:: struct udo_mm *udo_mm_alloc(struct udo_mm *mm, const size_t size);

| Returns pointer to an allocated block of heap
| memory. The goal of this is to allocate a large
| block of memory once. If re-allocation required
| pass the previous large block to clone all data.
|
| Addresses returned from function should not
| be used to write to. Writable addresses
| are return from a call to :c:func:`udo_mm_sub_alloc`.

	.. list-table::
		:header-rows: 1

		* - Param
	          - Decription
		* - mm
		  - | If ``NULL`` the inital allocation will be performed.
		    | If not ``NULL`` must pass a pointer to a ``struct`` :c:struct:`udo_mm`.
		* - size
		  - | Size of data caller may allocate. If the
		    | size is greater than the larger block
		    | remapping of memory will occur.

	Returns:
		| **on success:** Pointer to a ``struct`` :c:struct:`udo_mm`
		| **on failure:** ``NULL``

=========================================================================================================================================

================
udo_mm_sub_alloc
================

.. c:function:: void *udo_mm_sub_alloc(struct udo_mm *mm, size_t size);

| Returns pointer to an allocated block of heap
| memory. From the allocated larger block of
| memory sub-allocate from that larger block.
|
| Addresses returned from function can be
| used for writing.

	.. list-table::
		:header-rows: 1

		* - Param
	          - Decription
		* - mm
		  - | Must pass a pointer to a ``struct`` :c:struct:`udo_mm`.
		* - size
		  - | Size of buffer to sub-allocate.

	Returns:
		| **on success:** Pointer to writable memory
		| **on failure:** ``NULL``

=========================================================================================================================================

=========================
udo_mm_sub_alloc_get_size
=========================

.. c:function:: void *udo_mm_sub_alloc_get_size(const void *data);

| Returns size of an allocated heap
| memory sub block.

	.. list-table::
		:header-rows: 1

		* - Param
	          - Decription
		* - data
		  - | Must pass address returned after
		    | call to :c:func:`udo_mm_sub_alloc`.

	Returns:
		| **on success:** Size of allocated sub block
		| **on failure:** (size_t)-1

=========================================================================================================================================

===========
udo_mm_free
===========

.. c:function:: void udo_mm_free(struct udo_mm *mm, const void *data);

| Wipes the bytes at a given subregion of memory.
| Shifts the memory after the subregion over to
| the start of the wiped subregion.
|
| **NOTE:** This function should be used sparingly
| as the caller would have to keep track of the
| new pointer address for every object allocated.
| It's better to only allocate memory if you know
| the address it resides in won't change. Usages
| of bounded buffer for strings is encouraged.

	.. list-table::
		:header-rows: 1

		* - Param
	          - Decription
		* - mm
		  - | Must pass a pointer to a ``struct`` :c:struct:`udo_mm`.
		* - data
		  - | Address to the data caller wants to zero out.

=========================================================================================================================================

==============
udo_mm_destroy
==============

.. c:function:: void udo_mm_destroy(struct udo_mm *mm);

| Free's the large block of allocated memory created after
| :c:func:`udo_mm_alloc` call.

	.. list-table::
		:header-rows: 1

		* - Param
	          - Decription
		* - flops
		  - | Must pass a pointer to a ``struct`` :c:struct:`udo_mm`.