1 Utilities library overview
2 ==========================
7 The utilities library implements the following data structures:
8 - bidirectional map: lely/util/bimap.h
9 - doubly linked list: lely/util/dllist.h
10 - pairing heap: lely/util/pheap.h
11 - red-black tree: lely/util/rbtree.h
12 - singly linked list: lely/util/sllist.h
14 All implementations are intrusive. The user must embed a node in the struct
15 containing the value to be stored. This is generally more performant than a
16 non-intrusive implementation. Moreover, it is trivial to build a non-intrusive
17 version on top of the intrusive implementation if necessary.
22 Bit counting and manipulation functions are provided in lely/util/bits.h and
25 Comparison functions for integers, pointers and strings can be found in
31 Functions to keep track of platform-dependent and platform-independent error
32 numbers can be found in lely/util/errnum.h, as well as functions to convert
33 error numbers to human-readable strings.
35 Diagnostic messages can be generated with the functions in lely/util/diag.h.
36 These functions support user-defined message handlers and several handlers are
37 predefined for printing diagnostic messages to screen, log files or Windows
40 On POSIX and Windows platforms, functions are provided to run a process in the
41 background as a daemon/service (see lely/util/daemon.h). Note that this
42 functionality can be disabled when liblely-util is built.
44 The byte order of integers and floating-point values is platform specific.
45 Functions to convert between native, big-endian and little-endian, and network
46 byte order can be found in lely/util/endian.h.
48 File and memory management
49 --------------------------
51 Accessing files is generally most convenient using memory maps. I/O performance
52 is improved and reading/writing is simplified, since the user can rely on
53 pointer manipulation instead of repeated calls to `read()`/`write()` and
54 `seek()`. Two file buffers are provided, one for reading (lely/util/frbuf.h) and
55 one for writing (lely/util/fwbuf.h). Both are implemented using native memory
56 maps, but provide a standard C fallback implementation if necessary. The write
57 buffer supports atomic access: the final file is only created (or replaced) if
58 all operations completed successfully.
60 A lightweight in-memory buffer with a similar API is provided in
66 According to the Unix philosophy, text streams are the universal interface. To
67 ease the implementation of parsers, several lexing functions are provided in
68 lely/util/lex.h. Corresponding printing functions can be found in
71 These functions are used to implement the INI parser and printer of the
72 configuration struct (lely/util/config.h), a simple string-based key-value store
78 Although the Lely libraries are written in C, a C++ interface is often
79 available. To simplify the task of providing such an interface, wrapper classes
80 can be found in lely/util/c_type.hpp for trivial, standard layout and incomplete
81 C types. See [doc/util/object.md](@ref md_doc_util_object) for a template of the
82 C and C++ interfaces for objects in the Lely libraries.
84 Callback functions in C typically have a user-provided void pointer as the last
85 parameter. This can be used to allow, for example, C++ member functions to be
86 called from C. lely/util/c_call.hpp contains a wrapper that allows any C++
87 callable to be used as a C callback function. See
88 [doc/util/callback.md](@ref md_doc_util_callback) for a detailed description of
89 the C and C++ callback interface.
94 Convenience functions to compare and manipulate `timespec` structs can be found
95 in lely/util/time.h. External clock and timer functions, with an API similar to
96 the POSIX clock and timer functions, can be found in lely/util/xtime.h.
1.8.14