comparison: docs/src/modules.md
docs/src/modules.md
- changeset 259
- 2f5dea574a75
- parent 256
- 2c21b42cf11d
- child 264
- 24f5484bae97
equal
deleted
inserted
replaced
| 258:d9f4285c795c | 259:2f5dea574a75 |
|---|---|
| 1 Modules | 1 Modules |
| 2 ======= | 2 ======= |
| 3 | |
| 4 UCX provides several modules for data structures and algorithms. | |
| 5 You may choose to use specific modules by inclueding the corresponding header | |
| 6 file. | |
| 7 Please note, that some modules make use of other UCX modules. | |
| 8 For instance, the [Allocator](#allocator) module is used by many other modules | |
| 9 to allow flexible memory allocation. | |
| 10 By default the header files are placed into an `ucx` directory within your | |
| 11 systems include directory. In this case you can use an module by including it | |
| 12 via `#include <ucx/MODULENAME.h>`. | |
| 13 Required modules are included automatically. | |
| 14 | |
| 15 <a name="allocator"></a> | |
| 16 | |
| 17 ## Allocator | |
| 18 | |
| 19 *Header file:* [allocator.h](api/allocator_8h.html) | |
| 20 *Required modules:* None. | |
| 21 | |
| 22 A UCX allocator consists of a pointer to the memory area / pool and four | |
| 23 function pointers to memory management functions operating on this memory | |
| 24 area / pool. These functions shall behave equivalent to the standard libc | |
| 25 functions `malloc`, `calloc`, `realloc` and `free`. | |
| 26 | |
| 27 The signature of the memory management functions is based on the signature | |
| 28 of the respective libc function but each of them takes the pointer to the | |
| 29 memory area / pool as first argument. | |
| 30 | |
| 31 As the pointer to the memory area / pool can be arbitrarily chosen, any data | |
| 32 can be provided to the memory management functions. One example is the | |
| 33 [UCX Memory Pool](#mempool). | |
| 34 | |
| 35 <a name="avl"></a> | |
| 36 | |
| 37 ## AVL Tree | |
| 38 | |
| 39 *Header file:* [avl.h](api/avl_8h.html) | |
| 40 *Required modules:* [Allocator](#allocator) | |
| 41 | |
| 42 This binary search tree implementation allows average O(1) insertion and | |
| 43 removal of elements (excluding binary search time). | |
| 44 All common binary tree operations are implemented. Furthermore, this module | |
| 45 provides search functions via lower and upper bounds. | |
| 46 | |
| 47 <a name="buffer"></a> | |
| 48 | |
| 49 ## Buffer | |
| 50 | |
| 51 *Header file:* [buffer.h](api/buffer_8h.html) | |
| 52 *Required modules:* None. | |
| 53 | |
| 54 Instances of this buffer implementation can be used to read from or to write to | |
| 55 memory like you would do with a stream. This allows the use of | |
| 56 `ucx_stream_copy` from the [Utilities](#utils) module to copy contents from one | |
| 57 buffer to another or from file or network streams to the buffer and | |
| 58 vice-versa. | |
| 59 | |
| 60 More features for convenient use of the buffer can be enabled, like automatic | |
| 61 memory management and automatic resizing of the buffer space. | |
| 62 See the documentation of the macro constants in the header file for more | |
| 63 information. | |
| 64 | |
| 65 <a name="list"></a> | |
| 66 | |
| 67 ## List | |
| 68 | |
| 69 *Header file:* [list.h](api/list_8h.html) | |
| 70 *Required modules:* [Allocator](#allocator) | |
| 71 | |
| 72 This module provides the data structure and several functions for a doubly | |
| 73 linked list. Among the common operations like insert, remove, search and sort, | |
| 74 we allow convenient iteration via a special `UCX_FOREACH` macro. | |
| 75 | |
| 76 <a name="logging"></a> | |
| 77 | |
| 78 ## Logging | |
| 79 | |
| 80 *Header file:* [logging.h](api/logging_8h.html) | |
| 81 *Required modules:* [Map](#map), [String](#string) | |
| 82 | |
| 83 The logging module comes with some predefined log levels and allows some more | |
| 84 customization. You may choose if you want to get timestamps or source file and | |
| 85 line number logged automatically when outputting a message. | |
| 86 | |
| 87 | |
| 88 <a name="map"></a> | |
| 89 | |
| 90 ## Map | |
| 91 | |
| 92 *Header file:* [map.h](api/map_8h.html) | |
| 93 *Required modules:* [Allocator](#allocator), [String](#string) | |
| 94 | |
| 95 This module provides a hash map implementation using murmur hash 2 and separate | |
| 96 chaining with linked lists. Similarly to the list module, we provide a | |
| 97 `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs. | |
| 98 | |
| 99 <a name="mempool"></a> | |
| 100 | |
| 101 ## Memory Pool | |
| 102 | |
| 103 *Header file:* [mempool.h](api/mempool_8h.html) | |
| 104 *Required modules:* [Allocator](#allocator) | |
| 105 | |
| 106 Here we have a concrete allocator implementation in the sense of a memory pool. | |
| 107 This pool allows you to register destructor functions for the allocated memory, | |
| 108 which are automatically called on the destruction of the pool. | |
| 109 But you may also register *independent* destructor functions within a pool in | |
| 110 case, some external library allocated memory for you, which you wish to be | |
| 111 destroyed together with this pool. | |
| 112 | |
| 113 <a name="properties"></a> | |
| 114 | |
| 115 ## Properties | |
| 116 | |
| 117 *Header file:* [properties.h](api/properties_8h.html) | |
| 118 *Required modules:* [Map](#map) | |
| 119 | |
| 120 This module provides load and store function for `*.properties` files. | |
| 121 The key/value pairs are stored within an UCX Map. | |
| 122 | |
| 123 <a name="stack"></a> | |
| 124 | |
| 125 ## Stack | |
| 126 | |
| 127 *Header file:* [stack.h](api/stack_8h.html) | |
| 128 *Required modules:* [Allocator](#allocator) | |
| 129 | |
| 130 This concrete implementation of an UCX Allocator allows you to grab some amount | |
| 131 of memory which is then handled as a stack. | |
| 132 Please note, that the term *stack* only refers to the behavior of this | |
| 133 allocator. You may still choose if you want to use stack or heap memory | |
| 134 for the underlying space. | |
| 135 | |
| 136 A typical use case is an algorithm where you need to allocate and free large | |
| 137 amounts of memory very frequently. | |
| 138 | |
| 139 <a name="string"></a> | |
| 140 | |
| 141 ## String | |
| 142 | |
| 143 *Header file:* [string.h](api/string_8h.html) | |
| 144 *Required modules:* [Allocator](#allocator) | |
| 145 | |
| 146 This module provides a safe implementation of bounded string. | |
| 147 Usually C strings do not carry a length. While for zero-terminated strings you | |
| 148 can easily get the length with `strlen`, this is not generally possible for | |
| 149 arbitrary strings. | |
| 150 The `sstr_t` type of this module always carries the string and its length to | |
| 151 reduce the risk of buffer overflows dramatically. | |
| 152 | |
| 153 <a name="test"></a> | |
| 154 | |
| 155 ## Testing | |
| 156 | |
| 157 *Header file:* [test.h](api/test_8h.html) | |
| 158 *Required modules:* None. | |
| 159 | |
| 160 This module provides a testing framework which allows you to execute test cases | |
| 161 within test suites. | |
| 162 To avoid code duplication within tests, we also provide the possibility to | |
| 163 define test subroutines. | |
| 164 | |
| 165 <a name="utils"></a> | |
| 166 | |
| 167 ## Utilities | |
| 168 | |
| 169 *Header file:* [utils.h](api/utils_8h.html) | |
| 170 *Required modules:* [Allocator](#allocator), [String](#string) | |
| 171 | |
| 172 In this module we provide very general utility function for copy and compare | |
| 173 operations. | |
| 174 We also provide several `printf` variants to conveniently print formatted data | |
| 175 to streams or strings. | |
| 176 |
