ucx: docs/src/modules.md@2f5dea574a75 (annotated)

docs/src/modules.md@2f5dea574a75 (annotated)

docs/src/modules.md

Sat, 28 Oct 2017 15:43:51 +0200

author: Mike Becker <universe@uap-core.de>
date: Sat, 28 Oct 2017 15:43:51 +0200
changeset 259: 2f5dea574a75
parent 256: 2c21b42cf11d
child 264: 24f5484bae97
permissions: -rw-r--r--

modules documentation

 Modules
 =======
 UCX provides several modules for data structures and algorithms.
 You may choose to use specific modules by inclueding the corresponding header
 file.
 Please note, that some modules make use of other UCX modules.
 For instance, the [Allocator](#allocator) module is used by many other modules
 to allow flexible memory allocation.
 By default the header files are placed into an `ucx` directory within your
 systems include directory. In this case you can use an module by including it
 via `#include <ucx/MODULENAME.h>`.
 Required modules are included automatically.
 <a name="allocator"></a>
 ## Allocator
 *Header file:* [allocator.h](api/allocator_8h.html)
 *Required modules:* None.
 A UCX allocator consists of a pointer to the memory area / pool and four
 function pointers to memory management functions operating on this memory
 area / pool. These functions shall behave equivalent to the standard libc
 functions `malloc`, `calloc`, `realloc` and `free`.
 The signature of the memory management functions is based on the signature
 of the respective libc function but each of them takes the pointer to the
 memory area / pool as first argument.
 As the pointer to the memory area / pool can be arbitrarily chosen, any data
 can be provided to the memory management functions. One example is the
 [UCX Memory Pool](#mempool).
 <a name="avl"></a>
 ## AVL Tree
 *Header file:* [avl.h](api/avl_8h.html)
 *Required modules:* [Allocator](#allocator)
 This binary search tree implementation allows average O(1) insertion and
 removal of elements (excluding binary search time).
 All common binary tree operations are implemented. Furthermore, this module
 provides search functions via lower and upper bounds.
 <a name="buffer"></a>
 ## Buffer
 *Header file:* [buffer.h](api/buffer_8h.html)
 *Required modules:* None.
 Instances of this buffer implementation can be used to read from or to write to
 memory like you would do with a stream. This allows the use of
 `ucx_stream_copy` from the [Utilities](#utils) module to copy contents from one
 buffer to another or from file or network streams to the buffer and
 vice-versa.
 More features for convenient use of the buffer can be enabled, like automatic
 memory management and automatic resizing of the buffer space.
 See the documentation of the macro constants in the header file for more
 information.
 <a name="list"></a>
 ## List
 *Header file:* [list.h](api/list_8h.html)
 *Required modules:* [Allocator](#allocator)
 This module provides the data structure and several functions for a doubly
 linked list. Among the common operations like insert, remove, search and sort,
 we allow convenient iteration via a special `UCX_FOREACH` macro.
 <a name="logging"></a>
 ## Logging
 *Header file:* [logging.h](api/logging_8h.html)
 *Required modules:* [Map](#map), [String](#string)
 The logging module comes with some predefined log levels and allows some more
 customization. You may choose if you want to get timestamps or source file and
 line number logged automatically when outputting a message.
 <a name="map"></a>
 ## Map
 *Header file:* [map.h](api/map_8h.html)
 *Required modules:* [Allocator](#allocator), [String](#string)
 This module provides a hash map implementation using murmur hash 2 and separate
 chaining with linked lists. Similarly to the list module, we provide a
 `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs.
 <a name="mempool"></a>
 ## Memory Pool
 *Header file:* [mempool.h](api/mempool_8h.html)
 *Required modules:* [Allocator](#allocator)
 Here we have a concrete allocator implementation in the sense of a memory pool.
 This pool allows you to register destructor functions for the allocated memory,
 which are automatically called on the destruction of the pool.
 But you may also register *independent* destructor functions within a pool in
 case, some external library allocated memory for you, which you wish to be
 destroyed together with this pool.
 <a name="properties"></a>
 ## Properties
 *Header file:* [properties.h](api/properties_8h.html)
 *Required modules:* [Map](#map)
 This module provides load and store function for `*.properties` files.
 The key/value pairs are stored within an UCX Map.
 <a name="stack"></a>
 ## Stack
 *Header file:* [stack.h](api/stack_8h.html)
 *Required modules:* [Allocator](#allocator)
 This concrete implementation of an UCX Allocator allows you to grab some amount
 of memory which is then handled as a stack.
 Please note, that the term *stack* only refers to the behavior of this
 allocator. You may still choose if you want to use stack or heap memory
 for the underlying space.
 A typical use case is an algorithm where you need to allocate and free large
 amounts of memory very frequently.
 <a name="string"></a>
 ## String
 *Header file:* [string.h](api/string_8h.html)
 *Required modules:* [Allocator](#allocator)
 This module provides a safe implementation of bounded string.
 Usually C strings do not carry a length. While for zero-terminated strings you
 can easily get the length with `strlen`, this is not generally possible for
 arbitrary strings.
 The `sstr_t` type of this module always carries the string and its length to
 reduce the risk of buffer overflows dramatically.
 <a name="test"></a>
 ## Testing
 *Header file:* [test.h](api/test_8h.html)
 *Required modules:* None.
 This module provides a testing framework which allows you to execute test cases
 within test suites.
 To avoid code duplication within tests, we also provide the possibility to
 define test subroutines.
 <a name="utils"></a>
 ## Utilities
 *Header file:* [utils.h](api/utils_8h.html)
 *Required modules:* [Allocator](#allocator), [String](#string)
 In this module we provide very general utility function for copy and compare
 operations.
 We also provide several `printf` variants to conveniently print formatted data
 to streams or strings.

Mercurial > hg > ucx / annotate

docs/src/modules.md@2f5dea574a75 (annotated)

docs/src/modules.md