Block Allocator
=================




---------------------------------------------------------------
Types
---------------------------------------------------------------



.. c:type:: ymo_blalloc_t

   Structure used to wrap stack-style block storage.


   .. code-block:: c
      :caption: Definition
   
      typedef struct ymo_blalloc {
          blit_t* current;
          blit_t* end;
          size_t  total;
          size_t  remain;
          blit_t  val[FLEXIBLE_ARRAY_MEMBER];
      } ymo_blalloc_t;


---------------------------------------------------------------
Functions
---------------------------------------------------------------



.. c:function:: ymo_blalloc_t* ymo_blalloc_create(size_t n)

   Create a block alloc pool.
   
   :param n: size, in bytes, of the pool to create.
   :returns: pointer to :c:type:`ymo_blalloc_t` on success; ``NULL``, otherwise.



.. c:macro:: YMO_BLALLOC

   Allocate a type from the block
   e.g. my_type_t* my_var = YMO_BLALLOC(block, my_type_t)


   .. code-block:: c
      :caption: Definition
   
      #define YMO_BLALLOC(b,t) \
              ymo_blalloc(b, alignof(t), sizeof(t))


.. c:function:: void* ymo_blalloc(ymo_blalloc_t* block, size_t a, size_t n)

   Allocate a type from the block (prefer :c:macro:`YMO_BLALLOC` ).
   
   e.g.:
   
   .. code-block:: c
   
      my_type_t* obj = ymo_blalloc(
          block, alignof(my_type_t), sizeof(my_type_t));
   
      char* my_str = ymo_blalloc(block, alignof(char), strlen(my_str));
   
   :param t_align: type alignment (per alignof)
   :param t_size: type size in bytes (per sizeof)
   :returns: allocated space on success; ``NULL`` with ``errno`` set on failure.



.. c:function:: char* ymo_blalloc_strdup(struct ymo_blalloc* block, const char* s)

   strdup implemented on top of blalloc.
   If there's space enough: you'll get a copy.
   Otherwise, it'll return NULL.
   
   :param block: memory block used to allocate storage for s
   :param s: the string to copy
   :returns: a pointer to the duplicated string on success; ``NULL`` with ``errno`` set, otherwise



.. c:function:: void ymo_blalloc_reset(ymo_blalloc_t* block)

   Reset a block alloc pool.
   
   :param block: the pool to reset



.. c:function:: void ymo_blalloc_free(ymo_blalloc_t* block)

   Free a block alloc **pool.**
   
   .. warning::
   
      This is the **pool** free function — i.e. it is used to free the
      :c:type:`ymo_blalloc_t` created by :c:type:`ymo_blalloc_create`.
   
      Don't call this function to free memory allocated allocated *from* a pool
      by :c:func:`ymo_blalloc`!
   
   
   
   :param block: the pool to free