admin/mlib
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add table of contents

Browse Source
This commit is contained in:
Patrick Pelissier committed 2023-04-12 20:35:22 +02:00
1 parent a8075cbb05
commit d2dccbf514
1 file changed
+85 -50
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+85 -50
View File
@@ -1,8 +1,52 @@
M\*LIB: Generic type-safe Container Library for C language 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 M\*LIB (M star lib) is a C library enabling to define and use **generic and
type safe container**, aka handling generic 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. 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: 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) ![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. 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. 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. Other targets exist. Mainly for development purpose.
How to use ## How to use
----------
To use these data structures, you first include the desired header, To use these data structures, you first include the desired header,
instantiate the definition of the structure and its associated methods 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. 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. 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 ### 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. 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: 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. 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 When a memory exhaustion is reached, the global macro "M\_MEMORY\_FULL" is called
and the function returns immediately after. 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, 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 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. 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 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. 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. Many other implementation of generic container libraries in C exist.
For example, a non exhaustive list is: 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. * [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). 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'. 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 The behavior of M\*LIB can be customized globally by defining the following macros
before including any headers of M\*LIB. 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. 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. 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. 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. 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 This macro indicates if the system header stdio.h shall be included
and the FILE functions be defined (=1) or not (=0). 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 Default value: 1
### M\_USE\_STDARG #### M\_USE\_STDARG
This macro indicates if the system header stdarg.h shall be included This macro indicates if the system header stdarg.h shall be included
and the va\_args functions be defined (=1) or not (=0). and the va\_args functions be defined (=1) or not (=0).
Default value: 1 (true) Default value: 1 (true)
### M\_USE\_SMALL\_NAME #### M\_USE\_SMALL\_NAME
This macro indicates if the small names (without the m\_ prefix) This macro indicates if the small names (without the m\_ prefix)
have to be defined or not. Historically, only the small name API 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 Default value: 1
### M\_USE\_CSTR\_ALLOC #### M\_USE\_CSTR\_ALLOC
Define the allocation size of the temporary strings created by M\_CSTR Define the allocation size of the temporary strings created by M\_CSTR
(including the final null char). (including the final null char).
Default value: 256. Default value: 256.
### M\_USE\_IDENTIFIER\_ALLOC #### M\_USE\_IDENTIFIER\_ALLOC
Define the allocation size of a C identifier in the source code Define the allocation size of a C identifier in the source code
(excluding the final nil char). (excluding the final nil char).
@@ -8200,7 +8235,7 @@ It is used to represent a C identifier by a C string.
Default value: 128 Default value: 128
### M\_USE\_THREAD\_BACKEND #### M\_USE\_THREAD\_BACKEND
Define the thread backend to use by m-thread.h: 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. 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) 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 -. - In this case, a single-thread code is used -.
Default value: 1 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). This macro indicates if the workers shall use the CLANG block extension (=1) or not (=0).
Default value: 1 (on clang), 0 (otherwise) 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). This macro indicates if the workers shall use the C++ lambda function (=1) or not (=0).
Default value: 1 (compiled in C++), 0 (otherwise) 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 Define the maximum iteration of the BACKOFF exponential scheme
for the synchronization waiting loop of multi-threading code. for the synchronization waiting loop of multi-threading code.
Default value: 6 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 Define the size of the private data (reserved to the serial implementation) in a serial object
(as a number of pointers or equivalent objects). (as a number of pointers or equivalent objects).
Default value: 4 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'. 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. 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. Define the default size of a segment for a deque structure.
Default value: 8 elements. Default value: 8 elements.
### M\_USE\_HASH\_SEED #### M\_USE\_HASH\_SEED
Define the seed to inject to the hash computation of an object. Define the seed to inject to the hash computation of an object.
Default value: 0 (predictable hash) 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. Use fast integer conversion algorithms instead of using the LIBC.
Default value: 1 (because it also generates smaller code). Default value: 1 (because it also generates smaller code).
### M\_MEMORY\_ALLOC #### M\_MEMORY\_ALLOC
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_MEMORY\_REALLOC #### M\_MEMORY\_REALLOC
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_MEMORY\_FULL #### M\_MEMORY\_FULL
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_RAISE\_FATAL #### M\_RAISE\_FATAL
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_ASSERT #### M\_ASSERT
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_ASSERT\_SLOW #### M\_ASSERT\_SLOW
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_ASSERT\_INIT #### M\_ASSERT\_INIT
See [m-core.h](#m-core) See [m-core.h](#m-core)
### M\_ASSERT\_INDEX #### M\_ASSERT\_INDEX
See [m-core.h](#m-core) See [m-core.h](#m-core)
# License ## License
All files of M\*LIB are distributed under the following license. All files of M\*LIB are distributed under the following license.