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