admin/mlib

0 Fork 0

T

Patrick Pelissier b537ae6b5d Fix issue with C++ not performing like C...

2017-07-04 23:34:41 +02:00

bench

Rename M_OPLIST_CAT into M_OPCAT, M_OPLIST_FLAT into M_OPFLAT

2017-05-01 17:24:22 +02:00

example

Rename examples.

2017-05-01 21:06:33 +02:00

tests

Fix issue with C++

2017-07-04 23:30:10 +02:00

.gitignore

Initial commit

2017-02-18 18:35:25 +01:00

depend.png

Reduce size.

2017-05-05 00:14:39 +02:00

LICENSE

Fix copyright owner.

2017-02-18 19:01:30 +01:00

m-algo.h

Add method _uniq for algo

2017-05-22 19:26:06 +02:00

m-array.h

Use of M_CONST_CAST for array.

2017-05-26 15:44:28 +02:00

m-atomic.h

Replace stdatomic.h (C11 standard compliant header) by a custom one

2017-04-13 21:50:16 +02:00

m-bitset.h

Clean up code.

2017-05-27 20:46:45 +02:00

m-buffer.h

Update TODO (priority queue needs their own headers).

2017-06-19 21:33:43 +02:00

m-core.h

Remove TODO

2017-07-02 19:42:43 +02:00

m-dict.h

Fix bugs in iterator of OA dict for next/previous.

2017-06-08 23:51:09 +02:00

m-i-list.h

Use of M_CONST_CAST for intrusive list.

2017-05-26 12:41:52 +02:00

m-i-shared.h

Fix bug

2017-05-10 17:54:48 +02:00

m-list.h

Use of M_CONST_CAST for list.

2017-05-26 15:44:18 +02:00

m-mempool.h

Update comment.

2017-05-26 12:27:04 +02:00

m-mutex.h

Remove outdated comment.

2017-03-27 14:23:26 +02:00

m-rbtree.h

Use of M_CONST_CAST

2017-05-26 15:48:57 +02:00

m-register.h

Rename macros:

2017-02-19 00:36:42 +01:00

m-shared.h

Use of M_CONST_CAST

2017-05-26 15:49:09 +02:00

m-snapshot.h

Use of M_CONST_CAST.

2017-05-26 15:49:23 +02:00

m-string.h

Replace cast by assign cast.

2017-05-28 20:56:50 +02:00

m-tuple.h

Rename M_OPLIST_CAT into M_OPCAT, M_OPLIST_FLAT into M_OPFLAT

2017-05-01 17:24:22 +02:00

m-variant.h

Fix issue with C++ not performing like C...

2017-07-04 23:34:41 +02:00

Makefile

clean target forward into bench directory

2017-05-02 15:12:49 +02:00

README.md

Update doc

2017-06-23 00:23:36 +02:00

README.md

M*LIB: a Generic type-safe Container Library in C language

Overview

M*LIB (M star lib) is a library allowing the programmer to use generic but type safe container in pure C language, aka handling generic containers. The objects within the containers can have proper constructor, destructor (and other methods): this will be handled by the library. This allows to construct fully recursive objects (container-of[...]-container-of-type-T).

This is more or less an equivalent to the C++ STL.

M*LIB should be portable to any systems that support C99 (or C11 for some very rare features). Compatibility with C++ was not aimed (as the library is totally useless in C++ - use the STL instead) but should be kept.

M*LIB is only composed of a set of headers. There is no C file. Just put the header in the search path of your compiler, and it will work. So there is no dependency (except some other headers of M*LIB).

One of M*LIB's design key is to ensure safety. This is done by multiple means:

in debug mode, the contracts of the function are checked, ensuring that the data are not corrupted. Buffer overflow are checked in this mode through bound checking.
very few casts are used within the library. Still the library can be used with the greatest level of warnings by a C compiler without any aliasing warning.
the genericity is not done directly by macro, but indirectly by making them define inline functions with the proper prototypes: this allows the calls to have proper warning checks and proper debugging.

M*LIB should still be quite-efficient: even if the implementation may not always be state of the art, there is no overhead in using this library rather than using direct C low-level access: the compiler is able to fully optimize the library calls since all the functions are declared as inline (See here).

M*LIB uses internally the 'malloc', 'realloc' and 'free' functions to handle the memory pool. This behavior can be overridden at different level. M*LIB default policy is to abort the program if there is a memory error. However, this behavior can also be customized.

M*LIB may use a lot of assertions in its implementation to ensure safety: it is highly recommended to properly define NDEBUG for released programs. Otherwise you may have a noticeable slow-down (up to a factor x10 in some cases).

M*LIB is distributed under BSD-2 simplified license.

It is strongly advised not to read the source to know how to use the library but rather read the examples or the tests.

Components

The available containers which doesn't require the user structure to be modified are:

m-array.h: header for creating array of generic type and of variable size,
m-list.h: header for creating single-linked list of generic type,
m-dict.h: header for creating generic dictionary or set of generic types,
m-tuple.h: header for creating arbitrary tuple of generic type,
m-rbtree.h: header for creating binary sorted tree,
m-variant.h: header for creating arbitrary variant of generic type,

The available containers of M*LIB for thread synchronization are:

m-buffer.h: header for creating fixed-size queue (or stack) of generic type,
m-snapshot: header for creating 'snapshot' buffer for passing data between a producer and a consumer running at different rates (thread safe). It ensures that the consumer only sees complete data with minimal lag, but the consumer doesn't expect to see every piece of data.
m-shared.h: header for creating shared pointer of generic type.

The following containers are intrusive (You need to modify your structure):

m-i-list.h: header for creating dual-linked intrusive list of generic type,
m-i-shared.h: header for creating intrusive shared pointer of generic type (Thread Safe),

Other headers offering other functionality are:

m-bitset.h: header for creating bit set,
m-string.h: header for creating variable-length string,
m-core.h: header for meta-programming with the C preprocessor.
m-mutex.h: header for providing a very thin layer across multiple implementation of mutex/threads.
m-algo.h: header for providing various generic algorithms to the previous containers.
m-atomic.h: header for encapsulating either C's stdatmic.h or C++'s atomic header.
m-mempool.h: header for creating specialized & fast memory allocator.

Each containers define their iterators.

Each header can be used separately from others: dependency between headers have been kept to the minimum.

Build & Installation

M*LIB is only composed of a set of headers, as such there is no build for the library. The library doesn't depend on any other library than the libc.

To run the test suite, run:

   make check

To generate the documentation, run:

   make doc

To install the headers, run:

   make install PREFIX=/my/directory/to/install

External Reference

Many other implementation of generic container libraries exist in C. For example, a non exhaustive list can be:

Each of theses can be classified into:

Everything is a pointer to void,
Header files are included multiple times with different macro values,
Macros are used to access structures in a generic way,
Macros are used to generate C code.

M*LIB's category is the last one. Some macros are also defined to access structure in a generic way, but they are optional. M*LIB main added value compared to other libraries is its oplist feature allowing it to support [container-of-...]container-of-type-T: list of array of dictionary are perfectly supported by M*LIB.

For the macro-preprocessing part, other libraries also exist. For example:

For the string library, there is for example:

The Better String Library (with a page which lists a lot of other string libraries).

How to use

To use these data structures, you include the desired header, instantiate the definition of the structure and its associated methods by using a macro _DEF. Then you use the defined functions. Let's see an example which is rather simple:

#include <stdio.h>
#include "m-list.h"

LIST_DEF(uint, unsigned int)      /* Define struct list_uint_t and its methods */

int main(void) {
   list_uint_t list ;             /* list_uint_t has been define above */
   list_uint_init(list);          /* All type needs to be initialized */
   list_uint_push_back(list, 42); /* Push 42 in the list */
   list_uint_push_back(list, 17); /* Push 17 in the list */
   list_it_uint_t it;             /* Define an iterator to scan each one */
   for(list_uint_it(it, list)     /* Start iterator on first element */
       ; !list_uint_end_p(it)     /* Until the end is not reached */
       ; list_uint_next(it)) {    /* Set the iterator to the next element*/
          printf("%d\n",          /* Get a reference to the underlying */
            *list_uint_cref(it)); /* data and print it */
   }
   list_uint_clear(list);         /* Clear all the list */
}

[ Do not forget to add -std=c99 (or c11) to your compile command to request a C99 compatible build ]

This looks like a typical C program except the line with 'LIST_DEF' which doesn't have any semi-colon at the end. And in fact, except this line, everything is typical C program and even macro free! The only macro is in fact LIST_DEF: this macro expands to the good type for the list of the defined type and to all the necessary functions needed to handle such type. It is heavily context dependent and can generate different code depending on it. You can use it as many times as needed to defined as many lists as you want.

This is equivalent to this C++ program using the STL:

#include <iostream>
#include <list>

typedef std::list<unsigned int> list_uint_t;
typedef std::list<unsigned int>::iterator list_it_uint_t;

int main(void) {
   list_uint_t list ;             /* list_uint_t has been define above */
   list.push_back(42);            /* Push 42 in the list */
   list.push_back(17);            /* Push 17 in the list */
   for(list_it_uint_t it = list.begin()  /* Iterator is first element*/
       ; it != list.end()         /* Until the end is not reached */
       ; ++it) {                  /* Set the iterator to the next element*/
       std::cout << *it << '\n';  /* Print the underlying data */
   }
}

As you can see, this is rather equivalent with the following remarks:

M*LIB requires an explicit definition of the instance of the list,
M*LIB code is more verbose in the method name,
M*LIB needs explicit construction and destruction (as plain old C requests),
M*LIB doesn't return a value to the underlying data but a pointer to this value:
- this was done for performance (it avoids copying all the data within the stack)
- and for generality reasons (some structure may not allow copying data).

Note: list_uint_t is internally defined as an array of structure of size 1. This has the following advantages:

you effectively reserve the data whenever you declare a variable,
you pass automatically the variable per reference for function calls,
you can not copy the variable by an affectation (you have to use the API instead).

You can also condense the M*LIB code by using the EACH & LET macros if you are not afraid of using syntactic macros:

#include <stdio.h>
#include "m-list.h"

LIST_DEF(uint, unsigned int)        /* Define struct list_uint_t and its methods */

int main(void) {
   M_LET(list, LIST_OPLIST(uint)) { /* Define & init list as list_uint_t */
     list_uint_push_back(list, 42); /* Push 42 in the list */
     list_uint_push_back(list, 17); /* Push 17 in the list */
     for M_EACH(item, list, LIST_OPLIST(uint)) {
       printf("%d\n", *item);       /* Print the item */
     }
   }                                /* Clear of list will be done now */
}

Another example with a complete type (with proper initialization & clear function) by using the GMP library:

#include <stdio.h>
#include <gmp.h>
#include "m-array.h"

ARRAY_DEF(mpz, mpz_t, (INIT(mpz_init), INIT_SET(mpz_init_set), SET(mpz_set), CLEAR(mpz_clear)) )

int main(void) {
   array_mpz_t array ;             /* array_mpz_t has been define above */
   array_mpz_init(array);          /* All type needs to be initialized */
   mpz_t z;                        /* Define a mpz_t type */
   mpz_init(z);                    /* Initialize the z variable */
   mpz_set_ui (z, 42);
   array_mpz_push_back(array, z);  /* Push 42 in the array */
   mpz_set_ui (z, 17);
   array_mpz_push_back(array, z); /* Push 17 in the array */
   array_it_mpz_t it;              /* Define an iterator to scan each one */
   for(array_mpz_it(it, array)     /* Start iterator on first element */
       ; !array_mpz_end_p(it)      /* Until the end is not reached */
       ; array_mpz_next(it)) {     /* Set the iterator to the next element*/
          gmp_printf("%Zd\n",      /* Get a reference to the underlying */
            *array_mpz_cref(it));  /* data and print it */
   }
   mpz_clear(z);                   /* Clear the z variable */
   array_mpz_clear(array);         /* Clear all the array */
}

or the equivalent:

#include <stdio.h>
#include <gmp.h>
#include "m-array.h"

ARRAY_DEF(mpz, mpz_t, M_CLASSIC_OPLIST(mpz) )
#define ARRAY_OP ARRAY_OPLIST(mpz, M_CLASSIC_OPLIST(mpz))

int main(void) {
  M_LET(array, ARRAY_OP)
   M_LET (z, M_CLASSIC_OPLIST(mpz)) {
     mpz_set_ui (z, 42);
     array_mpz_push_back(array, z);  /* Push 42 in the array */
     mpz_set_ui (z, 17);
     array_mpz_push_back(array, z); /* Push 17 in the array */
     for M_EACH(item, array, ARRAY_OP) {
          gmp_printf("%Zd\n", *item);
     }
   }
}

Other examples are available in the example folder.

You may not use the internal fields of the structure. Internal fields of the structure are subject to change even for small revision of the library.

The final goal of the library is to be able to write code like this in pure C while keeping type safety and compile time name resolution:

let(list, list_uint_t) {
  push(list, 42);
  push(list, 17);
  for each (item, list) {
    print(item, "\n");
  }
}

ERRORS & COMPILERS

When defining the oplist of a type using M*LIB, sometimes (often) the list of errors/warnings generated by the compiler can be (very) huge (specially with latest compilers), even if the error itself is minor. This is more or less the same as the use of template in C++. You should focus mainly on the first reported error/warning even if the link between what the compiler report and what the error is is not immediate. The error is always in the oplist definition. Examples of typical errors:

lack of inclusion of an header,
overriding locally operator names by macros (like NEW, DEL, INIT, OPLIST, ...),
lack of ( ) or double level of ( ) around the oplist,
an unknown variable (example using DEFAULT_OPLIST instead of M_DEFAULT_OPLIST),
a missing argument,
a missing mandatory operator in the oplist.

Another way to debug is to generate the preprocessed file (by usually calling the compiler with the '-E' option instead of '-c') and check what's wrong in the preprocessed file:

      cc -std=c99 -E test-file.c > test-file.i
      perl -pi -e 's/;/;\n/g' test-file.i
      cc -std=c99 -c -Wall test-file.i

If there is a warning reported by the compiler in the generated code, then there is definitely an error you should fix (except if it reports shadowed variables).

OPLIST

An OPLIST is a fundamental notion of M*LIB which hasn't be used in any other library. In order to know how to operate on a type, M*LIB needs additional information as the compiler doesn't know how to handle properly any type (contrary to C++). This is done by giving an operator list (or oplist in short) to any macro which needs to handle the type. As such, an oplist as only meaning within a macro expansion. Fundamentally, this is the exposed interface of a type with documentated operators.

An oplist is an unordered list of operator in the following format:

(OPERATOR1(function1), OPERATOR2(function2), ...)

The function 'function1' is used to handle 'OPERATOR1'. The function 'function2' is used to handle 'OPERATOR2'.

It is used to perform the association between the operation on a type and the function which performs this operation. Without an oplist, M*LIB has no way to known how to deal with your type and will deal with it like a classic C type.

A function name can be followed by M_IPTR in the oplist (for example: INIT(init_func M_IPTR) ) to specify that the function accept as its first argument a pointer to the type rather than the type itself (aka the prototype is init_func(type *) instead of init_func(type)). If you use the '[1]' trick (see below), you won't need this.

An oplist has no real form from a C language point of view. It is just an abstraction which disappears after the macro expansion step of the preprocessing.

For each object / container, an oplist is needed and the following operators are usually expected for an object:

INIT constructor(obj): initialize the object 'obj' into a valid state.
INIT_SET constructor(obj, org): initialize the object 'obj' into the same state as the object 'org'.
SET operator(obj, org): set the initialized object 'obj' into the same state as the initialized object org.
CLEAR destructor(obj): destroy the initialized object 'obj', releasing any attached memory. This method shall never fail.

INIT, INIT_SET & SET methods shall only fail due to memory errors.

Not all operators are needed within an oplist to handle a container. If some operator is missing, the associated default operator of the function is used. To use C integer or float types, the default constructors are perfectly fine: you may use M_DEFAULT_OPLIST to define the operator list of such types or you can just omit it.

NOTE: An iterator doesn't have a constructor nor destructor methods.

Memory Allocation

Memory Allocation functions can be set by overriding the following macros before using the _DEF macros:

M_MEMORY_ALLOC (type): return a pointer to a new object of type 'type'.
M_MEMORY_DEL (ptr): free the single object pointed by 'ptr'.
M_MEMORY_REALLOC (type, ptr, number): return a pointer to an array of 'number' objects of type 'type', reusing the old array pointed by 'ptr'. 'ptr' can be NULL, in which case the array will be created.
M_MEMORY_FREE (ptr): free the array of objects pointed by 'ptr'.

ALLOC & DEL operators are supposed to allocate fixed size single element object (no array). Theses objects are not expected to grow. REALLOC & FREE operators deal with allocated memory for growing objects. Do not mix pointers between both: a pointer allocated by ALLOC (resp. REALLOC) is supposed to be only freed by DEL (resp. FREE). There are separated 'free' operators to allow specialization in the allocator (a good allocator can take this hint into account).

M_MEMORY_ALLOC and M_MEMORY_REALLOC are supposed to return NULL in case of memory allocation failure. The defaults are 'malloc', 'free', 'realloc' and 'free'.

You can also overide the methods NEW, DEL, REALLOC & DEL in the oplist given to a container.

Out-of-memory error

When a memory exhaustion is reached, the global macro "M_MEMORY_FULL" is called and the function returns immediately after. The object remains in a valid (if previously valid) and unchanged state in this case. By default, the macro prints an error message and abort the program: handling non-trivial memory errors is hard, testing such cases is mandatory to avoid security holes, testing them is even harder, and this behavior is rather conservative. It can be overloaded to handle other policy for error handling like:

throwing an error (in which case, the user is responsible to free memory of the allocated objects - destructor can still be called),
set a global error and handle it when the function returns,
other policy.

This function takes the size in bytes of the memory which has been tried to be allocated.

If needed, this macro shall be defined prior to instantiate the structure.

API Documentation

M-LIST

This header is for creating single-linked list.

LIST_DEF(name, type, [, oplist])

Define the list 'list_##name##_t' which contains the objects of type 'type' and its associated methods as "static inline" functions. 'name' shall be a C identifier which will be used to identify the list. It will be used to create all the types and functions to handle the container. It shall be done once per type and per compilation unit. It also define the iterator list_it_##name##_t and its associated methods as "static inline" functions.

A fundamental property of a list is that the objects created within the list will remain at their initialized address, and won't moved due to a new element being pushed/popped in the list.

The object 'oplist' is expected to have at least the following operators (INIT, INIT_SET, SET and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

For this structure, the back is always the first element, and the front is the last element: the list grows from the back.

Example:

LIST_DEF(mpz, mpz_t,                                               \
	(INIT(mpz_init), INIT_SET(mpz_init_set), SET(mpz_set), CLEAR(mpz_clear)))

list_mpz_t my_list;

void f(mpz_t z) {
	list_mpz_push_back (my_list, z);
}

If the given oplist contain the method MEMPOOL, then LIST_DEF will create a dedicated mempool named with the given value of the method, optimized for this kind of list:

it creates a mempool using MEMPOOL_def named "list_name",
it creates a variable named with the value of MEMPOOL_LINKAGE used for linkage,
it overwrites memory allocation of the created list to use this mempool with this variable.

Using mempool allows to create heavily efficient list but it will be only worth the effort in some heavy performance context. The created mempool has to be initialized before using any methods of the created list by calling mempool_list_name_init(variable) and cleared by calling mempool_list_name_clear(variable).

Example:

    LIST_DEF(uint, unsigned int, (MEMPOOL(list_mpool), MEMPOOL_LINKAGE(static)))

    static void test_list (size_t n)
    {
      mempool_list_uint_init(list_mpool);
      M_LET(a1, LIST_OPLIST(uint)) {
          for(size_t i = 0; i < n; i++)
              list_uint_push_back(a1, rand_get() );
      }
      mempool_list_uint_clear(list_mpool);
    }

LIST_OPLIST(name [, oplist])

Return the oplist of the list defined by calling LIST_DEF with name & oplist.

Created methods

In the following methods, name stands for the name given to the macro which is used to identify the type. The following types are automatically defined by the previous macro:

list_name_t

Type of the list of 'type'.

list_it_name_t

Type of an iterator over this list.

The following methods are automatically and properly created by the previous macro.

void list_name_init(list_name_t list)

Initialize the list 'list' (aka constructor) to an empty list.

void list_name_init_set(list_name_t list, const list_name_t ref)

Initialize the list 'list' (aka constructor) and set it to the value of 'ref'.

void list_name_set(list_name_t list, const list_name_t ref)

Set the list 'list' to the value of 'ref'.

void list_name_init_move(list_name_t list, list_name_t ref)

Initialize the list 'list' (aka constructor) by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared and can no longer be used.

void list_name_move(list_name_t list, list_name_t ref)

Set the list 'list' (aka constructor) by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared and can no longer be used.

void list_name_clear(list_name_t list)

Clear the list 'list (aka destructor). The list can't be used anymore, except with a constructor.

void list_name_clean(list_name_t list)

Clean the list (the list becomes empty). The list remains initialized but is empty.

const type *list_name_back(const list_name_t list)

Return a constant pointer to the data stored in the back of the list.

void list_name_push_back(list_name_t list, type value)

Push a new element within the list 'list' with the value 'value' contained within.

type *list_name_push_raw(list_name_t list)

Push a new element within the list 'list' without initializing it and returns a pointer to the non-initialized data. The first thing to do after calling this function is to initialize the data using the proper constructor. This allows to use a more specialized constructor than the generic one. Return a pointer to the non-initialized data.

type *list_name_push_new(list_name_t list)

Push a new element within the list 'list' and initialize it with the default constructor of the type. Return a pointer to the initialized object.

void list_name_pop_back(type *data, list_name_t list)

Pop a element from the list 'list' and set *data to this value.

bool list_name_empty_p(const list_name_t list)

Return true if the list is empty, false otherwise.

void list_name_swap(list_name_t list1, list_name_t list2)

Swap the list 'list1' and 'list2'.

void list_name_it(list_it_name_t it, list_name_t list)

Set the iterator 'it' to the back(=first) element of 'list'. There is no destructor associated to this initialization.

void list_name_it\set(list_it_name_t it, const list_it_name_t ref)

Set the iterator 'it' to the iterator 'ref'. There is no destructor associated to this initialization.

bool list_name_end_p(const list_it_name_t it)

Return true if the iterator doesn't reference a valid element anymore.

bool list_name_last_p(const list_it_name_t it)

Return true if the iterator references the top(=last) element or if the iterator doesn't reference a valid element anymore.

bool list_name_it_equal_p(const list_it_name_t it1, const list_it_name_t it2)

Return true if the iterator it1 references the same element than it2.

void list_name_next(list_it_name_t it)

Move the iterator 'it' to the next element of the list, ie. from the back (=first) element to the front(=last) element.

type *list_name_ref(list_it_name_t it)

Return a pointer to the element pointed by the iterator. This pointer remains valid until the list is modified by another method.

const type *list_name_cref(const list_it_name_t it)

Return a constant pointer to the element pointed by the iterator. This pointer remains valid until the list is modified by another method.

type *list_name_get(const list_name_t list, size_t i)

Return a pointer to the element i-th of the list (from 0). It is assumed than i is within the size of the list.

const type *list_name_cget(const list_name_t list, size_t i)

Return a constant pointer to the element i-th of the list (from 0). It is assumed than i is within the size of the list.

size_t list_name_size(const list_name_t list)

Return the number elements of the list (aka size). Return 0 if there no element.

void list_name_insert(list_name_t list, const list_it_name_t it, const type x)

Insert 'x' after the position pointed by 'it' (which is an iterator of the list 'list') or if 'it' doesn't point anymore to a valid element of the list, it is added as the back (=first) element of the 'list'

void list_name_remove(list_name_t list, list_it_name_t it)

Remove the element 'it' from the list 'list'. After wise, 'it' points to the next element of the list.

void list_name_move_back(list_name_t list1, list_name_t list2, list_it_name_t it)

Move the element pointed by 'it' (which is an iterator of 'list2') from the list 'list2' to the back position of 'list1'. After wise, 'it' points to the next element of 'list2'.

void list_name_slice(list_name_t list1, list_name_t list2)

Move all the element of 'list2' into 'list1". After-wise, 'list2' is emptied.

void list_name_reverse(list_name_t list)

Reverse the order of the list.

void list_name_get_str(string_t str, const list_name_t list, bool append)

Generate a string representation of the list 'list' and set 'str' to this representation (if 'append' is false) or append 'str' with this representation (if 'append' is true). This method is only defined if the type of the element defines a GET_STR method itself.

void list_name_out_str(FILE *file, const list_name_t list)

Generate a string representation of the list 'list' and outputs it into the FILE 'file'. This method is only defined if the type of the element defines a OUT_STR method itself.

void list_name_in_str(FILE *file, const list_name_t list)

Read from the file 'file' a string representation of a list and set 'list' to this representation. This method is only defined if the type of the element defines a IN_STR method itself.

bool list_name_equal_p(const list_name_t list1, const list_name_t list2)

Return true if both lists 'list1' and 'list2' are equal. This method is only defined if the type of the element defines a EQUAL method itself.

M-ARRAY

ARRAY_DEF(name, type [, oplist])

Define the array 'array_##name##_t' which contains the objects of type 'type' and its associated methods as "static inline" functions. An array is a collection of element which are individually indexable. Compared to C arrays, the created methods handle automatically the size (aka growable array). 'name' shall be a C identifier which will be used to identify the container.

It also define the iterator array_it_##name##_t and its associated methods as "static inline" functions.

The object oplist is expected to have at least the following operators (INIT, INIT_SET, SET and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

Example:

ARRAY_DEF(mpfr_t, mpfr,                                                                  \
   (INIT(mpfr_init), INIT_SET(mpfr_init_set), SET(mpfr_set), CLEAR(mpfr_clear)))

array_mpfr_t my_array;

void f(mpfr_t z) {
	array_mpfr_push_back (my_array, z);
}

ARRAY_OPLIST(name [, oplist])

Return the oplist of the array defined by calling ARRAY_DEF with name & oplist.

Created methods

In the following methods, name stands for the name given to the macro which is used to identify the type. The following types are automatically defined by the previous macro:

array_name_t

Type of the array of 'type'.

array_it_name_t

Type of an iterator over this array.

The following methods are automatically and properly created by the previous macros:

void array_name_init(array_name_t array)

Initialize the array 'array' (aka constructor) to an empty array.

void array_name_init_set(array_name_t array, const array_name_t ref)

Initialize the array 'array' (aka constructor) and set it to the value of 'ref'.

void array_name_set(array_name_t array, const array_name_t ref)

Set the array 'array' to the value of 'ref'.

void array_name_init_move(array_name_t array, array_name_t ref)

Initialize the array 'array' (aka constructor) by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared.

void array_name_move(array_name_t array, array_name_t ref)

Set the array 'array' by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared.

void array_name_clear(array_name_t array)

Clear the array 'array (aka destructor).

void array_name_clean(array_name_t array)

Clean the array (the array becomes empty but remains initialized).

void array_name_push_back(array_name_t array, const type value)

Push a new element into the back of the array 'array' with the value 'value' contained within.

type *array_name_push_new(array_name_t array)

Push a new element into the back of the array 'array' and initialize it with the default constructor. Return a pointer to this element.

type *array_name_push_raw(array_name_t array)

Push a new element within the array 'array' without initializing it and return a pointer to the non-initialized data. The first thing to do after calling this function is to initialize the data using the proper constructor. This allows to use a more specialized constructor than the generic one.

void array_name_push_at(array_name_t array, size_t key, const type x)

Push a new element into the position 'key' of the array 'array' with the value 'value' contained within. 'key' shall be a valid position of the array: from 0 to the size of array (included).

void array_name_pop_back(type *data, array_name_t array)

Pop a element from the back of the array 'array' and set *data to this value.

const type *array_name_back(const array_name_t array)

Return a constant pointer to the last element of the array.

bool array_name_empty_p(const array_name_t array)

Return true if the array is empty, false otherwise.

size_t array_name_size(const array_name_t array)

Return the size of the array.

size_t array_name_capacity(const array_name_t array)

Return the capacity of the array.

void array_name_swap(array_name_t array1, array_name_t array2)

Swap the array 'array1' and 'array2'.

void array_name_set_at(array_name_t array, size_t i, type value)

Set the element 'i' of array 'array' to 'value'. 'i' shall be within the size of the array.

void array_name_set_at2(array_name_t array, size_t i, type value)

Set the element 'i' of array 'array' to 'value', increasing the size of the array if needed.

void array_name_resize(array_name_t array, size_t size)

Resize the array 'array' to the size 'size' (initializing or clearing elements).

void array_name_reserve(array_name_t array, size_t capacity)

Extend or reduce the capacity of the 'array' to a rounded value based on 'capacity'. If the given capacity is below the current size of the array, the capacity is set to the size of the array.

void array_name_pop_at(type *dest, array_name_t array, size_t key)

Set *dest to the value the element 'i' if dest is not NULL, Remove this element from the array. 'key' shall be within the size of the array.

void array_name_remove(array_name_t array, array_it_name_t it)

Remove the element pointed by the iterator 'it' from the array 'array'. 'it' shall be within the array. Afterwise 'it' points to the next element, or points to the end.

void array_name_remove_v(array_name_t array, size_t i, size_t j)

Remove the element 'i' (included) to the element 'j' (excluded) from the array. 'i' and 'j' shall be within the size of the array, and i < j.

void array_name_insert(array_name_t array, size_t i, const type x)

Insert the object 'x' at the position 'key' of the array. 'key' shall be within the size of the array.

void array_name_insert_v(array_name_t array, size_t i, size_t j)

Insert from the element 'i' (included) to the element 'j' (excluded) new empty elements to the array. 'i' and 'j' shall be within the size of the array, and i < j.

type *array_name_get(array_name_t array, size_t i)

Return a pointer to the element 'i' of the array. 'i' shall be within the size of the array.

const type *array_name_cget(const array_name_t it, size_t i)

Return a constant pointer to the element 'i' of the array. 'i' shall be within the size of the array.

void array_name_it(array_it_name_t it, array_name_t array)

Set the iterator 'it' to the first element of 'array'.

void array_name_it_set(array_it_name_t it1, array_it_name_t it2)

Set the iterator 'it1' to 'it2'.

bool array_name_end_p(array_it_name_t it)

Return true if the iterator doesn't reference a valid element anymore.

bool array_name_last_p(array_it_name_t it)

Return true if the iterator references the last element of the array, or doesn't reference a valid element.

bool array_name_it_equal_p(const array_it_name_t it1, const array_it_name_t it2)

Return true if both iterators point to the same element.

void array_name_next(array_it_name_t it)

Move the iterator 'it' to the next element of the array.

void array_name_previous(array_it_name_t it)

Move the iterator 'it' to the previous element of the array.

type *array_name_ref(array_it_name_t it)

Return a pointer to the element pointed by the iterator. This pointer remains valid until the array is modified by another method.

const type *array_name_cref(const array_it_name_t it)

Return a constant pointer to the element pointed by the iterator. This pointer remains valid until the array is modified by another method.

void array_name_get_str(string_t str, const array_name_t array, bool append)

Generate a string representation of the array 'array' and set 'str' to this representation (if 'append' is false) or append 'str' with this representation (if 'append' is true). This method is only defined if the type of the element defines a GET_STR method itself.

void array_name_out_str(FILE *file, const array_name_t array)

Generate a string representation of the array 'array' and outputs it into the FILE 'file'. This method is only defined if the type of the element defines a OUT_STR method itself.

void array_name_in_str(FILE *file, const array_name_t array)

Read from the file 'file' a string representation of a array and set 'array' to this representation. This method is only defined if the type of the element defines a IN_STR method itself.

bool array_name_equal_p(const array_name_t array1, const array_name_t array2)

Return true if both arrays 'array1' and 'array2' are equal. This method is only defined if the type of the element defines a EQUAL method itself.

M-DICT

DICT_DEF2(name, key_type, key_oplist, value_type, value_oplist)

Define the dictionary 'dict_##name##_t' and its associated methods as "static inline" functions. A dictionary (or associative array, map, symbol table) is an abstract data type composed of a collection of (key, value) pairs, such that each possible key appears at most once in the collection. 'name' shall be a C identifier which will be used to identify the container. Current implementation uses Hash-Table and as such, elements in the dictionary are unordered.

It shall be done once per type and per compilation unit. It also define the iterator dict_it_##name##_t and its associated methods as "static inline" functions.

The object oplists are expected to have the following operators (INIT, INIT_SET, SET and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object. The key_oplist shall also define the additional operators (HASH and EQUAL).

Interface is subjected to minor change.

Example:

DICT_DEF2(str, string_t, STRING_OPLIST, string_t, STRING_OPLIST)
dict_str_t my_dict;
void f(string_t key, string_t value) {
	dict_str_set_at (my_dict, key, value);
}

DICT_OPLIST(name, key_oplist, value_oplist)

Return the oplist of the dictionary defined by calling DICT_DEF2 with name & key_oplist & value_oplist.

DICT_SET_DEF2(name, key_type, key_oplist)

Define the set 'dict_##name##_t' and its associated methods as "static inline" functions. A set is a specialized version of a dictionary with no value.

It shall be done once per type and per compilation unit. It also define the iterator dict_it_##name##_t and its associated methods as "static inline" functions.

The oplist is expected to have the following operators (INIT, INIT_SET, SET, CLEAR, HASH and EQUAL), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

Interface is subjected to minor change.

Example:

DICT_SET_DEF2(strSet, string_t, STRING_OPLIST)
dict_strSet_t set;
void f(string_t key) {
	dict_strSet_set_at (set, key);
}

DICT_SET_OPLIST(name, key_oplist)

Return the oplist of the set defined by calling DICT_SET_DEF2 with name & key_oplist.

Created methods

In the following methods, name stands for the name given to the macro which is used to identify the type. The following types are automatically defined by the previous macro:

dict_name_t

Type of the dictionary of 'key_type' --> 'value_type'.

dict_it_name_t

Type of an iterator over this dictionary.

The following methods are automatically and properly created by the previous macro:

void dict_name_init(dict_name_t dict)

Initialize the dictionary 'dict' to be empty.

void dict_name_clear(dict_name_t dict)

Clear the dictionary 'dict'.

void dict_name_init_set(dict_name_t dict, const dict_name_t ref)

Initialize the dictionary 'dict' to be the same as 'ref'.

void dict_name_set(dict_name_t dict, const dict_name_t ref)

Set the dictionary 'dict' to be the same as 'ref'.

void dict_name_init_move(dict_name_t dict, dict_name_t ref)

Initialize the dictionary 'dict' by stealing as resource as possible from 'ref' and clear 'ref'.

void dict_name_move(dict_name_t dict, dict_name_t ref)

Set the dictionary 'dict' by stealing as resource as possible from 'ref' and clear 'ref'.

void dict_name_clean(dict_name_t dict)

Clean the dictionary 'dict'. 'dict' remains initialized.

size_t dict_name_size(const dict_name_t dict)

Return the number of elements of the dictionary.

value_type *dict_name_get(const dict_name_t dict, const key_type key)

Return a pointer to the value associated to the key 'key' in dictionary 'dict' or NULL if the key is not found.

void dict_name_set_at(dict_name_t dict, const key_type key, const value_type value)

Set the value referenced by key 'key' in the dictionary 'dict' to 'value'.

void dict_name_remove(dict_name_t dict, const key_type key)

Remove the element referenced by key 'key' in the dictionary 'dict'. Do nothing if 'key' is no present in the dictionary.

void dict_name_it(dict_it_name_t it, dict_name_t dict)

Set the iterator 'it' to the first element of 'dict'.

void dict_name_it_set(dict_it_name_t it, const dict_it_name_t ref)

Set the iterator 'it' to the same element than 'ref'.

bool dict_name_end_p(const dict_it_name_t it)

Return true if 'it' references no longer a valid element.

bool dict_name_last_p(const dict_it_name_t it)

Return true if 'it' references the last element if is no longer valid.

void dict_name_next(dict_it_name_t it)

Update the iterator 'it' to the next element.

dict_pair_name_t *dict_name_ref(dict_it_name_t it)

Return a pointer to the pair composed by the key and its value. 'key' element can not be modified. This pointer remains valid until the dictionary is modified by another method.

const dict_pair_name_t *dict_name_ref(dict_it_name_t it)

Return a constant pointer to the pair composed by the key and its value. This pointer remains valid until the dictionary is modified by another method.

void dict_name_get_str(string_t str, const dict_name_t dict, bool append)

Generate a string representation of the dict 'dict' and set 'str' to this representation (if 'append' is false) or append 'str' with this representation (if 'append' is true). This method is only defined if the type of the element defines a GET_STR method itself.

void dict_name_out_str(FILE *file, const dict_name_t dict)

Generate a string representation of the dict 'dict' and outputs it into the FILE 'file'. This method is only defined if the type of the element defines a OUT_STR method itself.

void dict_name_in_str(FILE *file, const dict_name_t dict)

Read from the file 'file' a string representation of a dict and set 'dict' to this representation. This method is only defined if the type of the element defines a IN_STR method itself.

bool dict_name_equal_p(const dict_name_t dict1, const dict_name_t dict2)

Return true if both dicts 'dict1' and 'dict2' are equal. This method is only defined if the type of the element defines a EQUAL method itself.

M-TUPLE

TUPLE_DEF2(name, (element1, type1, oplist1) [, ...])

Define the tuple 'name##_t' and its associated methods as "static inline" functions. A tuple is a finite ordered list of elements of different types. Each parameter of the macro is expected to be an element of the tuple. Each element is defined by three parameters within parenthesis: the element name, the element type and the element oplist. 'name' and 'element' shall be a C identifier which will be used to identify the container.

This is more or less like a C structure. The main added value compared to using a struct is that it generates also all the basic methods to handle it. In fact, it generates a C struct with the given type and element.

It shall be done once per type and per compilation unit.

The interface is subjected to change.

Example:

TUPLE_DEF2(pair, (key, string_t, STRING_OPLIST),
		 (value, mpz_t, (INIT(mpz_init), INIT_SET(mpz_init_set), SET(mpz_set), CLEAR(mpz_clear) )))
void f(void) {
	pair_t p1;
	pair_init (p1);
	string_set_str(p1->key, "HELLO");
	mpz_set_str(p1->value, "1742", 10);
	pair_clear(p1);
}

TUPLE_OPLIST(name, oplist1[, ...] )

Return the oplist of the tuple defined by calling TUPLE_DEF2 with the given name & the oplists.

Created methods

In the following methods, name stands for the name given to the macro which is used to identify the type. The following types are automatically defined by the previous macro:

name_t

Type of the defined tuple.

The following methods are automatically and properly created by the previous macros:

void name_init(name_t tuple)

Initialize the tuple 'tuple' (aka constructor) to an empty tuple.

void name_init_set(name_t tuple, const name_t ref)

Initialize the tuple 'tuple' (aka constructor) and set it to the value of 'ref'.

void name_init_set2(name_t tuple, const type1 element1[, ...])

Initialize the tuple 'tuple' (aka constructor) and set it to the value of the tuple ('element1'[, ...]).

void name_set(name_t tuple, const name_t ref)

Set the tuple 'tuple' to the value of 'ref'.

void name_init_move(name_t tuple, name_t ref)

Initialize the tuple 'tuple' (aka constructor) by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared. This method is created only if all oplists of the tuple define INIT_MOVE method.

void name_move(name_t tuple, name_t ref)

Set the tuple 'tuple' by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared. This method is created only if all oplists of the tuple define MOVE method.

void name_clear(name_t tuple)

Clear the tuple 'tuple (aka destructor).

const type1 *name_get_element1(const name_t tuple)

Return a constant pointer to the element 'element1' of the tuple. There is as many methods as there are elements.

void name_set_element1(name_t tuple, type1 element1)

Set the element of the tuple to 'element1' There is as many methods as there are elements.

int name_set_cmp(const name_t tuple1, const name_t tuple2)

Compare 'tuple1' to 'tuple2' using lexicographic order. This method is created only if all oplists of the tuple define CMP method.

int name_set_equal_p(const name_t tuple1, const name_t tuple2)

Return true if 'tuple1' and 'tuple2' are identical. This method is created only if all oplists of the tuple define EQUAL method.

void name_get_str(string_t str, const name_t tuple, bool append)

Generate a string representation of the tuple 'tuple' and set 'str' to this representation (if 'append' is false) or append 'str' with this representation (if 'append' is true). This method is only defined if all oplists define a GET_STR method.

void name_out_str(FILE *file, const name_t tuple)

Generate a string representation of the tuple 'tuple' and outputs it into the FILE 'file'. This method is only defined if all oplists define a OUT_STR method.

void name_in_str(FILE *file, const name_t tuple)

Read from the file 'file' a string representation of a tuple and set 'tuple' to this representation. This method is only defined if all oplists define a IN_STR method.

M-VARIANT

VARIANT_DEF2(name, (element1, type1, oplist1) [, ...])

Define the variant 'name##_t' and its associated methods as "static inline" functions. A variant is a finite exclusive list of elements of different types : the variant can be only equal to one element at a time. Each parameter of the macro is expected to be an element of the variant. Each element is defined by three parameters within parenthesis: the element name, the element type and the element oplist. 'name' and 'element' shall be a C identifier which will be used to identify the container.

This is more or less like a C union. The main added value compared to using a union is that it generates all the basic methods to handle it and it dynamically identifies which element is stored within.

It shall be done once per type and per compilation unit.

The interface is subjected to change.

Example:

VARIANT_DEF2(either, (key, string_t, STRING_OPLIST),
		 (value, mpz_t, (INIT(mpz_init), INIT_SET(mpz_init_set), SET(mpz_set), CLEAR(mpz_clear) )))
void f(sting_t s) {
	either_t p1;
	either_init (p1);
	either_set_key(p1, s);
	either_clear(p1);
}

VARIANT_OPLIST(name, oplist1[, ...] )

Return the oplist of the variant defined by calling VARIANT_DEF2 with the given name & the oplists.

Created methods

In the following methods, name stands for the name given to the macro which is used to identify the type. The following types are automatically defined by the previous macro:

name_t

Type of the defined variant.

The following methods are automatically and properly created by the previous macros:

void name_init(name_t variant)

Initialize the variant 'variant' (aka constructor) to be empty.

void name_init_set(name_t variant, const name_t ref)

Initialize the variant 'variant' (aka constructor) and set it to the value of 'ref'.

void name_set(name_t variant, const name_t ref)

Set the variant 'variant' to the value of 'ref'.

void name_init_move(name_t variant, name_t ref)

Initialize the variant 'variant' (aka constructor) by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared. This method is created only if all oplists of the variant define INIT_MOVE method.

void name_move(name_t variant, name_t ref)

void name_move_elementN(name_t variant, typeN ref)

Set the variant 'variant' by stealing as many resources from 'ref' as possible. After-wise 'ref' is cleared. This method is created only if all oplists of the variant define MOVE method.

void name_clear(name_t variant)

Clear the variant 'variant (aka destructor).

void name_clean(name_t variant)

Clean the variant 'variant and make it empty.

void name_set_elementN(name_t variant, const typeN elementN)

Set the variant 'variant' to the type and value of 'element1'.

typeN * name_get_elementN(name_t variant)

Return a pointer to the 'varian' viewed as of type 'typeN'. If the variant isn't an object of such type, it returns NULL.

bool name_empty_p(const name_t variant)

Return true if the variant is empty, false otherwise.

bool name_elementN_p(const name_t variant)

Return true if the variant is of the type of 'elementN'.

size_t name_hash(const name_t variant)

Return a hash associated to the variant. All types associated to the variant shall have a hash function for this function to be defined.

bool name_equal_p(const name_t variant1, const name_t varian2)

Return true if both objects are equal, false otherwise. All types associated to the variant shall have a equal_p function for this function to be defined.

void name_swap(name_t variant1, name_t varian2)

Swap both objects.

void name_get_str(string_t str, name_t variant, bool append)

Convert the variant into a string, appending it into 'str' or not. All types associated to the variant shall have a get_str function for this function to be defined.

void name_out_str(FILE *f, name_t variant)

Convert the variant into a string and send it to the stream 'f'. All types associated to the variant shall have a out_str function for this function to be defined.

void name_in_str(name_t variant, FILE *f)

Read a string representation of the variant from the stream 'f' and update the object variant with it. All types associated to the variant shall have a in_str function for this function to be defined.

M-RBTREE

RBTREE_DEF(name, type[, oplist])

Define the binary ordered tree 'rbtree_##name##_t' and its associated methods as "static inline" functions. A binary tree is a tree data structure in which each node has at most two children, which are referred to as the left child and the right child. In this kind of tree, all elements of the tree are totally ordered. The current implementation is RED-BLACK TREE. It shall not be confused with a B-TREE. 'name' shall be a C identifier which will be used to identify the container.

The CMP operator is used to perform the total ordering of the elements.

The UPDATE operator is used to update an element if the pushed item already exist in the container. The default behavior will overwrite the recorded value with the new one.

It shall be done once per type and per compilation unit. It also define the iterator rbtree_it_##name##_t and its associated methods as "static inline" functions.

The object oplist is expected to have the following operators (INIT, INIT_SET, SET, CMP and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

Example:

RBTREE_DEF(uint, unsigned int)
void f(unsigned int num) {
	rbtree_uint_t tree;
	rbtree_uint_init(tree);
	for(unsigned int i = 0; i < num; i++)
		rbtree_uint_push(tree, i);
	rbtree_uint_clear(tree);                              
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-BUFFER

BUFFER_DEF(name, type, size, policy[, oplist])

Define the buffer 'buffer_##name##_t' and its associated methods as "static inline" functions. A buffer is a fixed size queue or stack. 'name' shall be a C identifier which will be used to identify the container.

The size parameter defined the fixed size of the queue. It can be 0, in which case, the fixed size will be defined at initialization time.

Multiple additional policy can be applied to the buffer by performing a logical or of the following properties:

BUFFER_QUEUE : define a FIFO queue (default),
BUFFER_STACK : define a stack (exclusive with BUFFER_QUEUE),
BUFFER_BLOCKING : define blocking calls for push/pop (default),
BUFFER_UNBLOCKING : define unblocking calls for push/pop,
BUFFER_THREAD_SAFE : define thread safe functions (default),
BUFFER_THREAD_UNSAFE : define thread unsafe functions,
BUFFER_PUSH_INIT_POP_MOVE : change the behavior of PUSH as pushing a new object, and POP as moving this new object into the new emplacement (this is mostly used for performance reasons or to handle properly a shared_ptr semantic). In practice, it works as if POP performs the initialization of the object,
BUFFER_PUSH_OVERWRITE : PUSH will always overwrite the first entry (this is mostly used to reduce latency).

This container is designed to be used for easy synchronization inter-threads (and the variable shall be a global one).

It shall be done once per type and per compilation unit. It also define the iterator buffer_it_##name##_t and its associated methods as "static inline" functions.

The object oplist is expected to have the following operators (INIT, INIT_SET, SET, INIT_MOVE and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

Example:

BUFFER_DEF(uint, unsigned int, 10, BUFFER_QUEUE|BUFFER_BLOCKING)

buffer_uint_t g_buff;

void f(unsigned int i) {
	buffer_uint_init(g_buff, 10);
	buffer_uint_push(g_buff, i);
	buffer_uint_pop(&i, g_buff);
	buffer_uint_clear(g_buff);
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-SNAPSHOT

This header is for created snapshots.

SNAPSHOT_DEF(name, type[, oplist])

Define the snapshot 'snapshot_##name##_t' and its associated methods as "static inline" functions. A snapshot is a mechanism to allows a consumer thread and a produce thread, working at different speeds, to exchange messages in a reliable and thread safe way (the message is passed atomatically). In practice, it is implemented using a triple buffer.

This container is designed to be used for easy synchronization inter-threads (and the variable shall be a global one).

It shall be done once per type and per compilation unit. No all functions are thread safe.

The object oplist is expected to have the following operators (INIT, INIT_SET, SET and CLEAR), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object. It can have the optional methods INIT_MOVE and MOVE.

Example:

SNAPSHOT_DEF(uint, unsigned int)
void f(unsigned int * i) {
	snapshot_uint_t t;
	snapshot_uint_init(t);
	i = snapshot_uint_take(t);
	*i = 1;
	i = snapshot_uint_look(t);
	snapshot_uint_clear(t);
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-SHARED

This header is for creating shared pointer.

SHARED_PTR_DEF(name, type[, oplist])

Define the shared pointer 'shared_##name##_t' and its associated methods as "static inline" functions. A shared pointer is a mechanism to keep tracks of all users of an object and performs an automatic destruction of the object whenever all users release their need on this object.

The destruction of the object is thread safe.

The object oplist is expected to have the following operators (CLEAR and DEL), otherwise default operators are used. If there is no given oplist, the default operators are also used. The created methods will use the operators to init, set and clear the contained object.

There are designed to work with buffers with policy BUFFER_PUSH_INIT_POP_MOVE to send a shared pointer across multiple threads.

Example:

SHARED_PTR_DEF(mpz, mpz_t, (CLEAR(mpz_clear)))
void f(void) {
	shared_mpz_t p;
	mpz_t z;
	mpz_init(z);
	shared_mpz_init2 (p, z);
	buffer_uint_push(g_buff1, p);
	buffer_uint_push(g_buff2, p);
	shared_mpz_clear(p);
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-I-SHARED

This header is for creating intrusive shared pointer.

ISHARED_PTR_DEF(name, type[, oplist])

Extend an object by adding the necessary interface to handle it as a shared pointer and define the associated methods to handle it as "static inline" functions. A shared pointer is a mechanism to keep tracks of all users of an object and performs an automatic destruction of the object whenever all users release their need on this object.

The destruction of the object is thread safe.

There are designed to work with buffers with policy BUFFER_PUSH_INIT_POP_MOVE to send a shared pointer across multiple threads.

It is recommended to use the intrusive shared pointer over the standard one if possible. (They are faster & cleaner).

Example:

    typedef struct mystruct_s {
            ISHARED_PTR_INTERFACE(mystruct, mystruct_s);
            char *message;
    } mystruct_t;

    static void mystruct_clear(mystruct_t *p) { free(p->message); }

    ISHARED_PTR_DEF(mystruct, mystruct_t, (CLEAR(mystruct_clear M_IPTR)))

    void f(void) {
            mystruct_t *p = ishared_mystruct_new();
            p->message = strdup ("Hello");
            buffer_mystruct_push(g_buff1, p);
            buffer_mystruct_push(g_buff2, p);
            ishared_mystruct_clear(p);
    }

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-I-LIST

This header is for creating intrusive dual-chained list.

ILIST_DEF(name, type[, oplist])

Extend an object by adding the necessary interface to handle it within a dual linked list, define the dual linked list and define the associated methods to handle it as "static inline" functions. 'name' shall be a C identifier which will be used to identify the list. It will be used to create all the types and functions to handle the container. It shall be done once per type and per compilation unit.

An object is expected to be part of only one list of a kind in the entire program at a time. An intrusive list allows to move from an object to the next object without needing to go through the entire list, or to remove an object from a list in O(1). It may, or may not, be better than standard list. It depends on the context.

Example:

typedef struct test_s {
  int n;
  ILIST_INTERFACE (tname, struct test_s);
} test_t;

ILIST_DEF(tname, test_t)

void f(void) {
	test_t x1, x2, x3;
	ilist_tname_t list;

	x1.n = 1;
	x2.n = 2;
	x3.n = 3;

	ilist_tname_init(list);
	ilist_tname_push_back (list, &x3);
	ilist_tname_push_front (list, &x1);
	ilist_tname_push_after (&x1, &x2);

	int n = 1;
	for M_EACH(item, list, ILIST_OPLIST(tname)) {
		assert (n == item->n);
		n++;
	}
	ilist_tname_clear(list);
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-BITSET

This header is for using bitset.

A bitset can be seen as a specialized version of an array of bool, where each item takes only 1 bit. It allows for compact representation of such array.

Example:

void f(void) {
	bitset_t set;
	bitset_init(set);
	for(int i = 0; i < 100; i ++)
		bitset_push_back(set, i%2);
	bitset_clear(set);
}

methods

The methods are mostly the same than for an array. The following methods are available:

TODO: document the API.

M-STRING

This header is for using dynamic string. The size of the string is automatically updated in function of the needs.

Example:

void f(void) {
	string_t s1;
	string_init (s1);
	string_set_str (s1, "Hello, world!");
	string_clear(s1);
}

methods

The following methods are available:

TODO: document the API.

M-CORE

This header is the internal core of M*LIB, providing a lot of functionality by extending a lot the preprocessing capability. Working with these macros is not easy and the developer needs to know how the macro preprocessing works. It also adds the needed macro for handling the oplist. As a consequence, it is needed by all other header files.

Some macros are using recursivity to work. This is not an easy feat to do as it needs some tricks to work (see reference). This still work well with only one major limitation: it can not be chained. For example, if MACRO is a macro implementing recursivity, then MACRO(MACRO()) won't work.

Example:

M_MAP(f, 1, 2, 3, 4)
M_REDUCE(f, g, 1, 2, 3, 4)
M_SEQ(1, 20, f)

Compiler Macros

The following compiler macros are available:

M_ASSUME(cond)

M_ASSUME is equivalent to assert, but gives hints to compiler about how to optimize the code if NDEBUG is defined.

M_LIKELY(cond) / M_UNLIKELY(cond)

M_LIKELY / M_UNLIKELY gives hints on the compiler of the likehood of the given condition.

Preprocessing macro extension

M_MAX_NB_ARGUMENT

Maximum number of argument which can be handled by this header.

M_C(a,b), M_C3(a,b,c), M_C4(a,b,c,d)

Return a symbol corresponding to the concatenation of the input arguments.

M_INC(number)

Increment the number given as argument (from [0..29[) and return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage). If number is not within the range, the behavior is undefined.

M_DEC(number)

Decrement the number given as argument (from [0..29[) and return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage). If number is not within the range, the behavior is undefined.

M_RET_ARG1(arglist,...) / M_RET_ARG2(...) / M_RET_ARG3(...) / M_RET_ARG27(...)

Return the argument 1 of the given arglist (respectively 2, 3, and 27). The argument shall exist in the arglist.

M_BOOL(cond)

Convert an integer or a symbol into 0 (if 0) or 1 (if not 0 or symbol unknown). Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_INV(cond)

Inverse 0 into 1 and 1 into 0. It is undefined if cond is not 0 or 1 (use M_BOOL to convert). Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_AND(cond1, cond2)

Perform a logical 'and' between cond1 and cond2. cond1 and cond2 shall be 0 or 1 otherwise it is undefined. Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_OR(cond1, cond2)

Perform a logical 'or' between cond1 and cond2. cond1 and cond2 shall be 0 or 1 otherwise it is undefined. Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_IF(cond)(action_if_true, action_if_false)

Return the pre-processing token 'action_if_true' if 'cond' is true, action_if_false otherwise (meaning it is evaluated at macro processing stage, not at compiler stage). cond shall be 0 or 1 otherwise it is undefined.

M_COMMA_P(arglist)

Return 1 if there is a comma inside the argument list, 0 otherwise. Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_EMPTY_P(expression)

Return 1 if the argument 'expression' is 'empty', 0 otherwise. Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_DEFERRED_COMMA

Return a comma ',' at a later phase of the macro processing steps.

M_IF_EMPTY(cond)(action_if_true, action_if_false)

Return the pre-processing token 'action_if_true' if 'cond' is empty, action_if_false otherwise (meaning it is evaluated at macro processing stage, not at compiler stage). cond shall be 0 or 1 otherwise it is undefined.

M_PARENTHESIS_P(expression)

Return 1 if the argument 'expression' starts a parenthesis and ends it (like '(...)'), 0 otherwise. Return a pre-processing token corresponding to this value (meaning it is evaluated at macro processing stage, not at compiler stage).

M_DELAY1(expr) / M_DELAY2(expr) / M_DELAY3(expr) / M_DELAY4(expr) / M_ID

Delay the evaluation by 1, 2, 3 or 4 steps. This is necessary to write macros which are recursive. The argument is a macro-function which has to be deferred. M_ID is an equivalent of M_DELAY1.

M_EVAL(expr)

Perform a complete stage evaluation of the given expression, removing recursive expression within it. Only ONE M_EVAL expression is expected in the evaluation chain. Can not be chained.

M_APPLY(func, args...)

Apply 'func' to '(args...) ensuring that a() isn't evaluated until all 'args' have been also evaluated. It is used to delay evaluation.

M_APPLY_FUNC(func, arg1)

Apply 'func' to 'arg1' if 'arg1' is not empty.

M_APPLY_FUNC2(func, arg1, arg2)

Apply 'func' to 'arg1, arg2' if 'arg2' is not empty.

M_MAP(func, args...)

Apply 'func' to each argument of the 'args...' list of argument.

M_MAP2(func, data, args...)

Apply 'func' to each couple '(data, argument)' with argument an element of the 'args...' list.

M_MAP_PAIR(func, args...)

Map a macro to all given pair of arguments (Using recursivity). Can not be chained.

M_REDUCE(funcMap, funcReduce, args...)

Map the macro funcMap to all given arguments 'args' and reduce all theses computation with the macro 'funcReduce' (using recursivity) Can not be chained.

M_REDUCE2(funcMap, funcReduce, data, args...)

Map the macro funcMap to all pair (data, arg) of the given argument list 'args' and reduce all theses computation with the macro 'funcReduce'. Do not use recursivity.

M_SEQ(init, end, macro, data)

Generate a sequence of number from 'init' to 'end' and apply to the macro the pair '(data, num)' for each number 'num' of the sequence (using recursivity).

M_NARGS(args...)

Return the number of argument of the given list. Doesn't work for empty argument.

M_IF_NARGS_EQ1(argslist)(action_if_one_arg, action_otherwise)

Return the pre-processing token 'action_if_one_arg' if 'argslist' has only one argument, action_otherwise otherwise (meaning it is evaluated at macro processing stage, not at compiler stage).

M_IF_NARGS_EQ2(argslist)(action_if_two_arg, action_otherwise)

Return the pre-processing token 'action_if_two_arg' if 'argslist' has two arguments, action_otherwise otherwise (meaning it is evaluated at macro processing stage, not at compiler stage).

M_IF_DEBUG(action)

Return the pre-processing token 'action' if the build is compiled in debug mode (i.e. NDEBUG is undefined).

M_NOTEQUAL(x, y)

Return 1 if x != y, 0 otherwise (resolution is performed at preprocessing time). x and y shall be within the maximum argument value.

M_EQUAL(x, y)

Return 1 if x == y, 0 otherwise (resolution is performed at preprocessing time). x and y shall be within the maximum argument value.

M_ADD(x, y)

Return x+y (resolution is performed at preprocessing time). x and y shall be within the maximum argument value (using recursivity).

M_SUB(x, y)

Return x-y (resolution is performed at preprocessing time). x and y shall be within the maximum argument value and x >= y (using recursivity).

M_INVERT(args...)

Reverse the argument list. For example, if args was a,b,c, it return c,b,a.

C11 Macro

Theses macros are only valid if the program is built in C11 mode:

M_PRINTF_FORMAT(x)

Return the printf format associated to the type of 'x'. 'x' shall be printable with printf.

M_PRINT_ARG(x)

Print using printf the variable 'x'. The format of 'x' is deduced.

M_FPRINT_ARG(file, x)

Print into a file 'file' using fprintf the variable 'x'. The format of 'x' is deduced.

M_PRINT(args...)

Print using printf all the variable in 'args'. The format of the arguments are deduced.

M_FPRINT(file, args...)

Print into a file 'file' using fprintf all the variables in 'args'. The format of 'x' is deduced.

M_AS_TYPE(type, x)

Within a C11 _Generic statement, all expressions shall be valid C expression even if the case if always false, and is not executed. This can seriously limit the _Generic statement. This macro overcomes this limitation by returning :

either the input 'x' if it is of type 'type',
or the value 0 view as a type 'type'.

So the returned value is always of type 'type' and is safe in a _Generic statement.

C Macro

Theses macros expand their code at compilation level:

M_MIN(x, y)

Return the minimum of 'x' and 'y'. x and y shall not have any side effect.

M_MAX(x, y)

Return the maximum of 'x' and 'y'. x and y shall not have any side effect.

M_POWEROF2_P(n)

Return true if 'n' is a power of 2. n shall not have any side effect.

M_SWAP(type, a, b)

Swap the values of 'a' and 'b'. 'a' and 'b' are of type 'type'. a and b shall not have any side effect.

M_ASSIGN_CAST(type, a)

Check if 'a' can be assigned to a temporary of type 'type' and returns this temporary. If it cannot, the compilation failed.

M_CONST_CAST(type, a)

Check if 'a' can be properly casted to (const type *) and returns this casted pointer if possible. If it cannot, the compilation failed.

M_TYPE_FROM_FIELD(type, ptr, fieldType, field)

Assuming 'ptr' is a pointer to a fieldType object which is stored within a structure of type 'type' at the position 'field', it returns a pointer to the structure.

HASH Functions

M_HASH_SEED --> size_t

User shall overwrite this macro by a random seed (of type size_t) before including the header m-core.h o that all hash functions will use this variable as a seed for the hash functions. If no user macro is defined, the default is to expand it to 0, making all hash computations predictible.

M_HASH_DECL(hash)

Declare and initialize a new hash computation, named 'hash' which is an integer.

M_HASH_UP(hash, value)

Update the 'hash' variable with the given 'value' by incorporating the 'value' within the 'hash'. 'value' can be up to a 'size_t' variable.

uint32_t m_core_hash (const void *str, size_t length)

Compute the hash of the binary representation of the data pointer by 'str' of length 'length'. 'str' shall have the same alignement restriction than an 'uint32_t'.

OPERATORS Functions

M_GET_INIT oplist

M_GET_INIT_SET oplist

M_GET_INIT_MOVE oplist

M_GET_SET oplist

M_GET_MOVE oplist

M_GET_SWAP oplist

M_GET_CLEAR oplist

M_GET_NEW oplist

M_GET_DEL oplist

M_GET_REALLOC oplist

M_GET_FREE oplist

M_GET_MEMPOOL oplist

M_GET_MEMPOOL_LINKAGE oplist

M_GET_HASH oplist

M_GET_EQUAL oplist

M_GET_CMP oplist

M_GET_UPDATE oplist

M_GET_TYPE oplist

M_GET_SUBTYPE oplist

M_GET_OPLIST oplist

M_GET_SORT oplist

M_GET_IT_TYPE oplist

M_GET_IT_FIRST oplist

M_GET_IT_LAST oplist

M_GET_IT_END oplist

M_GET_IT_SET oplist

M_GET_IT_END_P oplist

M_GET_IT_LAST_P oplist

M_GET_IT_EQUAL_P oplist

M_GET_IT_NEXT oplist

M_GET_IT_PREVIOUS oplist

M_GET_IT_REF oplist

M_GET_IT_CREF oplist

M_GET_ADD oplist

M_GET_SUB oplist

M_GET_MUL oplist

M_GET_DIV oplist

M_GET_CLEAN oplist

M_GET_PUSH oplist

M_GET_POP oplist

M_GET_REVERSE oplist

M_GET_GET_STR oplist

M_GET_OUT_STR oplist

M_GET_IN_STR oplist

M_GET_SEPARATOR oplist

M_GET_EXT_ALGO oplist

M_GET_EXPECTED_SIZE oplist

M_GET_OOR_SET oplist

M_GET_OOR_EQUAL oplist

Return the associated method to the given operator within the given oplist.

M_DEFAULT_OPLIST

Default oplist for C standard types (int & float)

M_CSTR_OPLIST

Default oplist for the C type const char *

M_CLASSIC_OPLIST(name)

Create the oplist with the classic operators using the pattern 'name', i.e. name##_init, name##_clear, etc.

M_OPFLAT oplist

Remove the parenthesis around an oplist.

M_OPCAT(oplist1,oplist2)

Concat two oplists in one. 'oplist1''s operators will have higher priority to 'oplist2'

M_OPEXTEND(oplist, ...)

Extend an oplist with the given list of operators. Theses new operators will have higher priority than the ones in the given oplist.

M_TEST_METHOD_P(method, oplist)

Test if a method is present in an oplist. Return 0 or 1.

M_IF_METHOD(method, oplist)

Perfom a preprocessing M_IF, if the method is present in the oplist. Example: M_IF_METHOD(HASH, oplist)(define function which uses HASH method, )

M_IF_METHOD_BOTH(method, oplist1, oplist2)

Perform a preprocessing M_IF if the method exists in both oplist. Example: M_IF_METHOD_BOTH(HASH, oplist1, oplist2) (define function , )

M_IF_METHOD_ALL(method, ...)

Perform a preprocessing M_IF if the method exists for all oplist. Example: M_IF_METHOD_ALL(HASH, oplist1, oplist2, oplist3) (define function, )

M_IPTR

By putting this after a method for an operator in the oplist, it specifies that the first argument of the moethod shall be a pointer to the destination type, rather than the type.

M_DO_INIT_MOVE(oplist, dest, src)

M_DO_MOVE(oplist, dest, src)

Perform an INIT_MOVE/MOVE if present, or emulate it otherwise. Note: default methods for INIT_MOVE/MOVE are not robust enough yet.

Syntax enhancing

M_EACH(item, container, oplist)

This macro allows to iterate over the given 'container' of oplist 'oplist'. It shall be used after the for C keyword. 'item' will be a created pointer variable to the underlying type, only available within the 'for'. There can only have one M_EACH per line. Example: for M_EACH(item, list, LIST_OPLIST) { action; }

M_LET(var1[,var2[,...]], oplist)

This macro allows to define the variable 'var1'(resp. var2, ...) of oplit 'oplist', initialize 'var1' (resp. var2, ...) by calling the initialization method, and clear 'var1' (resp. var2, ...) by calling the initialization method when the bracket associated to the M_LET go out of scope. There can only have one M_LET per line. Example:

 M_LET(a, STRING_OPLIST) { do something with a }  or
 M_LET(a, b, c, STRING_OPLIST) { do something with a, b & c }

NOTE: The user code can not perform a return or a goto outside the {} otherwise the clear code of the object won't be called .

Memory functions

type *M_MEMORY_ALLOC (type)

Return a pointer to a new allocated object of type 'type'. The object is not initialized. In case of allocation error, it returns NULL. The default function is the malloc function. It can be overriden before including the header m-core.h

void M_MEMORY_DEL (type *ptr)

Delete the cleared object pointed by the pointer 'ptr'. The pointer was previously allocated by the macro M_MEMORY_ALLOC. 'ptr' can not be NULL. The default function is the free function. It can be overriden before including the header m-core.h

type *M_MEMORY_REALLOC (type, ptr, number)

Return a pointer to an array of 'number' objects of type 'type'. The objects are not initialized, nor the state of previous objects changed. 'ptr' is either NULL, or pointer returned from a previous call of M_MEMORY_REALLOC. In case of allocation error, it returns NULL. The default function is the realloc function. It can be overriden before including the header m-core.h

void M_MEMORY_FREE (type *ptr)

Delete the cleared object pointed by the pointer 'ptr'. The pointer was previously allocated by the macro M_MEMORY_REALLOC. 'ptr' can not be NULL. The default function is the free function. It can be overriden before including the header m-core.h A pointer allocated by M_MEMORY_ALLOC can not be freed by this function.

void M_MEMORY_FULL (size_t size)

This macro is called when a memory exception error shall be raised. It can be overriden before including the header m-core.h The default is to abort the execution. The macro can :

abort the execution,
throw an exception (In this case, the state of the object is unchanged),
set a global error variable and return.

NOTE: The last case is not 100% supported.

void M_INIT_FAILURE (void)

This macro is called when an initialization error shall be raised. It can be overriden before including the header m-core.h The default is to abort the execution. The macro can :

abort the execution,
throw an exception (In this case, the state of the object is unchanged),
set a global error variable and return.

NOTE: The last case is not currently supported.

void M_ASSERT_INIT_FAILURE(expression)

This macro is called when an assertion in an initialization context is called. If the expression is false, the execution is aborted. The assertion is kept in release programs. It can be overriden before including the header m-core.h The default is to abort the execution.

M-MUTEX

This header is for providing very thin layer around OS implementation of threads, conditional variables and mutexs. It has backends for WIN32, POSIX thread or C11 thread.

It was needed due to the low adoption rate of the C11 equivalent layer.

Example:

m_thread_t idx_p;
m_thread_t idx_c;

m_thread_create (idx_p, conso_function, NULL);
m_thread_create (idx_c, prod_function, NULL);
m_thread_join (idx_p;
m_thread_join (idx_c);

methods

The following methods are available:

m_mutex_t

A type representating a mutex.

void m_mutex_init(mutex)

Initialize the variable mutex of type m_mutex_t. If the initialization fails, the program aborts.

void m_mutex_clear(mutex)

Clear the variable mutex of type m_mutex_t. If the variable is not initialized, the behavior is undefined.

void m_mutex_lock(mutex)

Lock the variable mutex of type m_mutex_t for exclusive use. If the variable is not free, it will wait indefinitely until it is. If the variable is not initialized, the behavior is undefined.

void m_mutex_unlock(mutex)

Unlock the variable mutex of type m_mutex_t for exclusive use. If the variable is not locked, the behavior is undefined. If the variable is not initialized, the behavior is undefined.

M_LOCK_DECL(name)

Define the lock 'name'. This shall be called in the global space (reserved for global variables).

M_LOCK(name)

Use the lock 'name': the encapsulation instructions are protected by the lock. Example:

    M_LOCK_DECL(n_lock);
    unsigned long n = 0;
    void f(void) {
         M_LOCK(n_lock) {
           n ++;
         }
    }

m_cond_t

A type representating a conditionnal variable, used within a mutex section.

void m_cond_init(m_cond_t cond)

Initialize the conditional variable cond of type m_cond_t. If the initialization failed, the program aborts.

void m_cond_clear(m_cond_t cond)

Clear the variable cond of type m_cond_t. If the variable is not initialized, the behavior is undefined.

void m_cond_signal(m_cond_t cond)

Within a mutex exclusive section, signal that the event associated to the variable cond of type m_cond_t has occured to other threads. If the variable is not initialized, the behavior is undefined.

void m_cond_wait(m_cond_t cond, m_mutex_t mutex)

Within a mutex exclusive section defined by mutex, wait indefinitely for the event associated to the variable cond of type m_cond_t to occur. IF multiple threads wait for the same event, which thread to awoken is not specified. If any variable is not initialized, the behavior is undefined.

m_thread_t

A type representating an id of a thread.

void m_thread_create(m_thread_t thread, void (function)(void), void *argument)

Create a new thread and set the it of the thread to 'thread'. The new thread run the code function(argument) with argument a 'void *' and function taking a 'void *' and returning nothing. If the initialization fails, the program aborts.

void m_thread_join(m_thread_t thread)

Wait indefinetly for the thread 'thread' to exit.

M-ALGO

This header is for generating generic algorithm to containers.

ALGO_DEF(name, container_oplist)

Define the available algorithms for the container which oplist is container_oplist. The defined algorithms depend on the availability of the methods of the containers (For example, if there no CMP operation, there is no MIN operation defined).

Example:

ARRAY_DEF(int, int)
ALGO_DEF(algo_array, ARRAY_OPLIST(int))
void f(void) {
	array_int_t l;
	array_int_init(l);
	for(int i = 0; i < 100; i++)
		array_int_push_back (l, i);
	array_int_push_back (l, 17);
	assert( algo_array_contains(l, 62) == true);
	assert( algo_array_contains(l, -1) == false);
	assert( algo_array_count(l, 17) == 2);
	array_int_clear(l);
}

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

TODO: document the API.

M-MEMPOOL

This header is for generating specialized optimized memory pools: it will generate specialized functions to alloc & free only one kind of an object. The mempool functions are not thread safe for a given mempool.

MEMPOOL_DEF(name, type)

Generate specialized functions named 'name' to alloc & free a 'type' object.

Example:

MEMPOOL_DEF(uint, unsigned int)

void f(void) {
      mempool_uint_t m;
      mempool_uint_init(m);
      unsigned int *p = mempool_uint_alloc(m);
      mempool_uint_free(m, p);
      mempool_uint_clear(m);
    }

Created methods

The following methods are automatically and properly created by the previous macros. In the following methods, name stands for the name given to the macro which is used to identify the type.

mempool_name_t

The type of a mempool.

void mempool_name_init(mempool_name_t m)

Initialize the mempool 'm'.

void mempool_name_clear(mempool_name_t m)

Clear the mempool 'm'. All allocated objects associated to the this mempool which weren't explicitly freed will be deleted too (without calling their clear method).

type *mempool_name_alloc(mempool_name_t m)

Create a new object of type 'type' and return a new pointer to the uninitialized object.

void mempool_name_free(mempool_name_t m, type *p)

Free the object 'p' created by the call to mempool_name_alloc. The clear method of the type is not called.

M*LIB is a library of generic and type safe containers / data structures in pure C language (C99 / C11) for a wide collection of container (comparable to the C++ STL).

algorithms array bitset c collections data-structures generic hashmap json list lock-free priority-queue queue set stack string tree tuples variant

Readme BSD-2-Clause

10 MiB

0 Stars 1 Watchers 0 Forks