1.1 --- a/docs/src/modules.md Sat Oct 28 11:25:27 2017 +0200
1.2 +++ b/docs/src/modules.md Sat Oct 28 15:43:51 2017 +0200
1.3 @@ -1,2 +1,176 @@
1.4 Modules
1.5 =======
1.6 +
1.7 +UCX provides several modules for data structures and algorithms.
1.8 +You may choose to use specific modules by inclueding the corresponding header
1.9 +file.
1.10 +Please note, that some modules make use of other UCX modules.
1.11 +For instance, the [Allocator](#allocator) module is used by many other modules
1.12 +to allow flexible memory allocation.
1.13 +By default the header files are placed into an `ucx` directory within your
1.14 +systems include directory. In this case you can use an module by including it
1.15 +via `#include <ucx/MODULENAME.h>`.
1.16 +Required modules are included automatically.
1.17 +
1.18 +<a name="allocator"></a>
1.19 +
1.20 +## Allocator
1.21 +
1.22 +*Header file:* [allocator.h](api/allocator_8h.html)
1.23 +*Required modules:* None.
1.24 +
1.25 +A UCX allocator consists of a pointer to the memory area / pool and four
1.26 +function pointers to memory management functions operating on this memory
1.27 +area / pool. These functions shall behave equivalent to the standard libc
1.28 +functions `malloc`, `calloc`, `realloc` and `free`.
1.29 +
1.30 +The signature of the memory management functions is based on the signature
1.31 +of the respective libc function but each of them takes the pointer to the
1.32 +memory area / pool as first argument.
1.33 +
1.34 +As the pointer to the memory area / pool can be arbitrarily chosen, any data
1.35 +can be provided to the memory management functions. One example is the
1.36 +[UCX Memory Pool](#mempool).
1.37 +
1.38 +<a name="avl"></a>
1.39 +
1.40 +## AVL Tree
1.41 +
1.42 +*Header file:* [avl.h](api/avl_8h.html)
1.43 +*Required modules:* [Allocator](#allocator)
1.44 +
1.45 +This binary search tree implementation allows average O(1) insertion and
1.46 +removal of elements (excluding binary search time).
1.47 +All common binary tree operations are implemented. Furthermore, this module
1.48 +provides search functions via lower and upper bounds.
1.49 +
1.50 +<a name="buffer"></a>
1.51 +
1.52 +## Buffer
1.53 +
1.54 +*Header file:* [buffer.h](api/buffer_8h.html)
1.55 +*Required modules:* None.
1.56 +
1.57 +Instances of this buffer implementation can be used to read from or to write to
1.58 +memory like you would do with a stream. This allows the use of
1.59 +`ucx_stream_copy` from the [Utilities](#utils) module to copy contents from one
1.60 +buffer to another or from file or network streams to the buffer and
1.61 +vice-versa.
1.62 +
1.63 +More features for convenient use of the buffer can be enabled, like automatic
1.64 +memory management and automatic resizing of the buffer space.
1.65 +See the documentation of the macro constants in the header file for more
1.66 +information.
1.67 +
1.68 +<a name="list"></a>
1.69 +
1.70 +## List
1.71 +
1.72 +*Header file:* [list.h](api/list_8h.html)
1.73 +*Required modules:* [Allocator](#allocator)
1.74 +
1.75 +This module provides the data structure and several functions for a doubly
1.76 +linked list. Among the common operations like insert, remove, search and sort,
1.77 +we allow convenient iteration via a special `UCX_FOREACH` macro.
1.78 +
1.79 +<a name="logging"></a>
1.80 +
1.81 +## Logging
1.82 +
1.83 +*Header file:* [logging.h](api/logging_8h.html)
1.84 +*Required modules:* [Map](#map), [String](#string)
1.85 +
1.86 +The logging module comes with some predefined log levels and allows some more
1.87 +customization. You may choose if you want to get timestamps or source file and
1.88 +line number logged automatically when outputting a message.
1.89 +
1.90 +
1.91 +<a name="map"></a>
1.92 +
1.93 +## Map
1.94 +
1.95 +*Header file:* [map.h](api/map_8h.html)
1.96 +*Required modules:* [Allocator](#allocator), [String](#string)
1.97 +
1.98 +This module provides a hash map implementation using murmur hash 2 and separate
1.99 +chaining with linked lists. Similarly to the list module, we provide a
1.100 +`UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs.
1.101 +
1.102 +<a name="mempool"></a>
1.103 +
1.104 +## Memory Pool
1.105 +
1.106 +*Header file:* [mempool.h](api/mempool_8h.html)
1.107 +*Required modules:* [Allocator](#allocator)
1.108 +
1.109 +Here we have a concrete allocator implementation in the sense of a memory pool.
1.110 +This pool allows you to register destructor functions for the allocated memory,
1.111 +which are automatically called on the destruction of the pool.
1.112 +But you may also register *independent* destructor functions within a pool in
1.113 +case, some external library allocated memory for you, which you wish to be
1.114 +destroyed together with this pool.
1.115 +
1.116 +<a name="properties"></a>
1.117 +
1.118 +## Properties
1.119 +
1.120 +*Header file:* [properties.h](api/properties_8h.html)
1.121 +*Required modules:* [Map](#map)
1.122 +
1.123 +This module provides load and store function for `*.properties` files.
1.124 +The key/value pairs are stored within an UCX Map.
1.125 +
1.126 +<a name="stack"></a>
1.127 +
1.128 +## Stack
1.129 +
1.130 +*Header file:* [stack.h](api/stack_8h.html)
1.131 +*Required modules:* [Allocator](#allocator)
1.132 +
1.133 +This concrete implementation of an UCX Allocator allows you to grab some amount
1.134 +of memory which is then handled as a stack.
1.135 +Please note, that the term *stack* only refers to the behavior of this
1.136 +allocator. You may still choose if you want to use stack or heap memory
1.137 +for the underlying space.
1.138 +
1.139 +A typical use case is an algorithm where you need to allocate and free large
1.140 +amounts of memory very frequently.
1.141 +
1.142 +<a name="string"></a>
1.143 +
1.144 +## String
1.145 +
1.146 +*Header file:* [string.h](api/string_8h.html)
1.147 +*Required modules:* [Allocator](#allocator)
1.148 +
1.149 +This module provides a safe implementation of bounded string.
1.150 +Usually C strings do not carry a length. While for zero-terminated strings you
1.151 +can easily get the length with `strlen`, this is not generally possible for
1.152 +arbitrary strings.
1.153 +The `sstr_t` type of this module always carries the string and its length to
1.154 +reduce the risk of buffer overflows dramatically.
1.155 +
1.156 +<a name="test"></a>
1.157 +
1.158 +## Testing
1.159 +
1.160 +*Header file:* [test.h](api/test_8h.html)
1.161 +*Required modules:* None.
1.162 +
1.163 +This module provides a testing framework which allows you to execute test cases
1.164 +within test suites.
1.165 +To avoid code duplication within tests, we also provide the possibility to
1.166 +define test subroutines.
1.167 +
1.168 +<a name="utils"></a>
1.169 +
1.170 +## Utilities
1.171 +
1.172 +*Header file:* [utils.h](api/utils_8h.html)
1.173 +*Required modules:* [Allocator](#allocator), [String](#string)
1.174 +
1.175 +In this module we provide very general utility function for copy and compare
1.176 +operations.
1.177 +We also provide several `printf` variants to conveniently print formatted data
1.178 +to streams or strings.
1.179 +
