Add table of contents
This commit is contained in:
Patrick Pelissier committed
1 parent
a8075cbb05
commit
d2dccbf514
1 file changed
+85
-50
@@ -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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user