diff --git a/README.md b/README.md index 724e2a0e..6ea1e4b0 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,52 @@ M\*LIB: Generic type-safe Container Library for C language ========================================================== -Overview --------- +1. [Overview](#overview) +2. [Components](#components) +3. [Build & Installation](#build--installation) +4. [How to use](#how-to-use) +5. [Performance](#performance) +6. [OPLIST](#oplist) +7. [Memory Allocation](#memory-allocation) +8. [Emplace construction](#emplace) +9. [Errors & compilers](#errors--compilers) +10. [External Reference](#external-reference) +11. [API Documentation](#api-documentation) + 1. [Generic methods](#generic-methods) + 2. [List](#m-list) + 3. [Array](#m-array) + 4. [Deque](#m-deque) + 5. [Dictionary](#m-dict) + 6. [Tuple](#m-tuple) + 7. [Variant](#m-variant) + 8. [Red/Black Tree](#m-rbtree) + 9. [B+ Tree](#m-bptree) + 10. [Generic Tree](#m-tree) + 11. [Priority queue](#m-prioqueue) + 12. [Fixed buffer queue](#m-buffer) + 13. [Atomic Shared Register](#m-snapshot) + 14. [Shared pointers](#m-shared) + 15. [Intrusie Shared Pointers](#m-i-shared) + 16. [Intrusive list](#m-i-list) + 17. [Concurrent adaptator](#m-concurrent) + 18. [Bitset](#m-bitset) + 19. [String](#m-string) + 20. [Core preprocessing](#m-core) + 21. [Thread](#m-thread) + 22. [Worker threads](#m-worker) + 23. [Atomic](#m-atomic) + 24. [Generic algorithms](#m-algo) + 25. [Function objects](#m-funcobj) + 26. [Exception handling](#m-try) + 27. [Memory pool](#m-mempool) + 28. [JSON Serialization](#m-serial-json) + 29. [Binary Serialization](#m-serial-bin) +12. [Global User Customization](#global-user-customization) +13. [Licence](#license) + + + +## Overview M\*LIB (M star lib) is a C library enabling to define and use **generic and type safe container**, aka handling generic @@ -89,8 +133,7 @@ mandatory to follow under penalty of undefined behavior. All pointers expected by the functions of the library shall expect non-null argument except if indicated. -Components ----------- +## Components The following headers define containers that don't require the user structure to be modified: @@ -149,8 +192,7 @@ Each header can be used separately from others: dependency between headers have ![Dependence between headers](https://raw.githubusercontent.com/P-p-H-d/mlib/master/doc/depend.png) -Build & Installation --------------------- +## 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. @@ -170,8 +212,7 @@ To install the headers, run: Other targets exist. Mainly for development purpose. -How to use ----------- +## How to use To use these data structures, you first include the desired header, instantiate the definition of the structure and its associated methods @@ -453,8 +494,7 @@ The final goal of the library is to be able to write code like this in pure C wh } ``` -Performance ------------ +## Performance M\*LIB performance is compared to the one of GNU C++ STL (v10.2) in the following graphs. Each graph is presented first in linear scale and then in logarithmic scale to better realize the differences. @@ -485,8 +525,7 @@ The results for several different libraries are also available [in a separate pa -OPLIST ------- +## OPLIST ### Definition @@ -895,8 +934,9 @@ This is pretty useless, except if you enable exceptions... In which case, this enables you to close the file even if an exception is thrown. -Memory Allocation ------------------ +## Memory Allocation + +### Customization Memory Allocation functions can be globally set by overriding the following macros before using the definition \_DEF macros: @@ -919,8 +959,7 @@ You can also override the methods NEW, DEL, REALLOC & DEL in the oplist given to so that only the container will use these memory allocation functions instead of the global ones. -Out-of-memory error -------------------- +### Out-of-memory error When a memory exhaustion is reached, the global macro "M\_MEMORY\_FULL" is called and the function returns immediately after. @@ -948,8 +987,7 @@ If needed, this macro shall be defined ***prior*** to instantiate the structure. -Emplace construction --------------------- +## Emplace construction For M\*LIB, 'emplace' means pushing a new object in the container, while not giving it a copy of the new object, but the parameters needed @@ -989,8 +1027,7 @@ The GAIA specifies that the output (ARG1) is set as return value, ARG2 is given as the first argument, and a third constant argument is used. -ERRORS & COMPILERS ------------------- +## ERRORS & COMPILERS M\*LIB implements internally some controls to reduce the list of errors/warnings generated by a compiler when it detects some violation in the use of oplist by use of static assertion. @@ -1049,8 +1086,7 @@ For GCC / CLANG, uses -Werror=incompatible-pointer-types -External Reference ------------------- +## External Reference Many other implementation of generic container libraries in C exist. For example, a non exhaustive list is: @@ -1125,8 +1161,7 @@ For the string part, there is the following libraries for example: * [VSTR](http://www.and.org/vstr/) with a [page](http://www.and.org/vstr/comparison) that lists a lot of other string libraries. -API Documentation ------------------ +## API Documentation The M*LIB reference card is available [here](http://htmlpreview.github.io/?https://github.com/P-p-H-d/mlib/blob/master/doc/Container.html). @@ -8146,7 +8181,7 @@ otherwise the behavior of the object is undefined. Clear the serialization object 'serial'. -# Global User Customization +## Global User Customization The behavior of M\*LIB can be customized globally by defining the following macros before including any headers of M\*LIB. @@ -8155,14 +8190,14 @@ the default value will be used. Theses macros shall not be defined after including any M\*LIB header. -### M\_USE\_UNDEF\_ATOMIC +#### M\_USE\_UNDEF\_ATOMIC Undefine the macro _Atomic in m-atomic.h if stdatomic.h is included. It is needed on MSYS2 due to a bug in their headers which is not fixed yet. Default value: 1 (undef) on MSYS2, 0 otherwise. -### M\_USE\_STDIO +#### M\_USE\_STDIO This macro indicates if the system header stdio.h shall be included and the FILE functions be defined (=1) or not (=0). @@ -8170,14 +8205,14 @@ If it is not included, the macro M\_RAISE\_FATAL shall be defined by the user. Default value: 1 -### M\_USE\_STDARG +#### M\_USE\_STDARG This macro indicates if the system header stdarg.h shall be included and the va\_args functions be defined (=1) or not (=0). Default value: 1 (true) -### M\_USE\_SMALL\_NAME +#### M\_USE\_SMALL\_NAME This macro indicates if the small names (without the m\_ prefix) have to be defined or not. Historically, only the small name API @@ -8185,14 +8220,14 @@ existed, so in order to keep API compatibility, the default is true. Default value: 1 -### M\_USE\_CSTR\_ALLOC +#### M\_USE\_CSTR\_ALLOC Define the allocation size of the temporary strings created by M\_CSTR (including the final null char). Default value: 256. -### M\_USE\_IDENTIFIER\_ALLOC +#### M\_USE\_IDENTIFIER\_ALLOC Define the allocation size of a C identifier in the source code (excluding the final nil char). @@ -8200,7 +8235,7 @@ It is used to represent a C identifier by a C string. Default value: 128 -### M\_USE\_THREAD\_BACKEND +#### M\_USE\_THREAD\_BACKEND Define the thread backend to use by m-thread.h: @@ -8210,97 +8245,97 @@ Define the thread backend to use by m-thread.h: Default value: auto-detect in function of the running system. -### M\_USE\_WORKER +#### M\_USE\_WORKER This macro indicates if the multi-thread code of m-worker.h shall be used (=1) or not (=0) - In this case, a single-thread code is used -. Default value: 1 -### M\_USE\_WORKER\_CLANG\_BLOCK +#### M\_USE\_WORKER\_CLANG\_BLOCK This macro indicates if the workers shall use the CLANG block extension (=1) or not (=0). Default value: 1 (on clang), 0 (otherwise) -### M\_USE\_WORKER\_CPP\_FUNCTION +#### M\_USE\_WORKER\_CPP\_FUNCTION This macro indicates if the workers shall use the C++ lambda function (=1) or not (=0). Default value: 1 (compiled in C++), 0 (otherwise) -### M\_USE\_BACKOFF\_MAX\_COUNT +#### M\_USE\_BACKOFF\_MAX\_COUNT Define the maximum iteration of the BACKOFF exponential scheme for the synchronization waiting loop of multi-threading code. Default value: 6 -### M\_USE\_SERIAL\_MAX\_DATA\_SIZE +#### M\_USE\_SERIAL\_MAX\_DATA\_SIZE Define the size of the private data (reserved to the serial implementation) in a serial object (as a number of pointers or equivalent objects). Default value: 4 -### M\_USE\_MEMPOOL\_MAX\_PER\_SEGMENT(type) +#### M\_USE\_MEMPOOL\_MAX\_PER\_SEGMENT(type) Define the number of elements to allocate in a segment per object of type 'type'. Default value: number of elements that fits in a 16KB page. -### M\_USE\_DEQUE\_DEFAULT\_SIZE +#### M\_USE\_DEQUE\_DEFAULT\_SIZE Define the default size of a segment for a deque structure. Default value: 8 elements. -### M\_USE\_HASH\_SEED +#### M\_USE\_HASH\_SEED Define the seed to inject to the hash computation of an object. Default value: 0 (predictable hash) -### M\_USE\_FAST\_STRING\_CONV +#### M\_USE\_FAST\_STRING\_CONV Use fast integer conversion algorithms instead of using the LIBC. Default value: 1 (because it also generates smaller code). -### M\_MEMORY\_ALLOC +#### M\_MEMORY\_ALLOC See [m-core.h](#m-core) -### M\_MEMORY\_REALLOC +#### M\_MEMORY\_REALLOC See [m-core.h](#m-core) -### M\_MEMORY\_FULL +#### M\_MEMORY\_FULL See [m-core.h](#m-core) -### M\_RAISE\_FATAL +#### M\_RAISE\_FATAL See [m-core.h](#m-core) -### M\_ASSERT +#### M\_ASSERT See [m-core.h](#m-core) -### M\_ASSERT\_SLOW +#### M\_ASSERT\_SLOW See [m-core.h](#m-core) -### M\_ASSERT\_INIT +#### M\_ASSERT\_INIT See [m-core.h](#m-core) -### M\_ASSERT\_INDEX +#### M\_ASSERT\_INDEX See [m-core.h](#m-core) -# License +## License All files of M\*LIB are distributed under the following license.