Tue, 27 Jun 2023 18:44:37 +0200
add web docs for buffer and stream copy
1 ---
2 title: UCX Features
3 ---
5 <div id="modules">
7 ------------------------ ------------------------- ------------------- ---------------------------------
8 [Allocator](#allocator) [String](#string) [Buffer](#buffer) [Memory Pool](#memory-pool)
9 [Iterator](#iterator) [Collection](#collection) [List](#list) [Map](#map)
10 [Utilities](#utilities)
11 ------------------------ ------------------------- ------------------- ---------------------------------
13 </div>
15 ## Allocator
17 *Header file:* [allocator.h](api/allocator_8h.html)
19 The UCX allocator provides an interface for implementing an own memory allocation mechanism.
20 Various function in UCX provide an additional alternative signature that takes an allocator as
21 argument. A default allocator implementation using the stdlib memory management functions is
22 available via the global symbol `cxDefaultAllocator`.
24 If you want to define your own allocator, you need to initialize the `CxAllocator` structure
25 with a pointer to an allocator class (containing function pointers for the memory management
26 functions) and an optional pointer to an arbitrary memory region that can be used to store
27 state information for the allocator. An example is shown below:
29 ```c
30 struct my_allocator_state {
31 size_t total;
32 size_t avail;
33 char[] mem;
34 };
36 static cx_allocator_class my_allocator_class = {
37 my_malloc_impl,
38 my_realloc_impl, // all these functions are somewhere defined
39 my_calloc_impl,
40 my_free_impl
41 };
43 CxAllocator create_my_allocator(size_t n) {
44 CxAllocator alloc;
45 alloc.cl = &my_allocator_class;
46 alloc.data = calloc(1, sizeof(struct my_allocator_state) + n);
47 return alloc;
48 }
50 void free_my_allocator(CxAllocator *alloc) {
51 free(alloc.data);
52 free(alloc);
53 }
54 ```
56 ## String
58 *Header file:* [string.h](api/string_8h.html)
60 UCX strings come in two variants: immutable (`cxstring`) and mutable (`cxmutstr`).
61 The functions of UCX are designed to work with immutable strings by default but in situations where it is necessary,
62 the API also provides alternative functions that work directly with mutable strings.
63 Functions that change a string in-place are, of course, only accepting mutable strings.
65 When you are using UCX functions, or defining your own functions, you are sometimes facing the "problem",
66 that the function only accepts arguments of type `cxstring` but you only have a `cxmutstr` at hand.
67 In this case you _should not_ introduce a wrapper function that accepts the `cxmutstr`,
68 but instead you should use the `cx_strcast()` function to cast the argument to the correct type.
70 In general, UCX strings are **not** necessarily zero-terminated. If a function guarantees to return zero-terminated
71 string, it is explicitly mentioned in the documentation of the respective function.
72 As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly
73 ensuring that the string is zero-terminated.
75 ## Buffer
77 *Header file:* [buffer.h](api/buffer_8h.html)
79 Instances of this buffer implementation can be used to read from or write to memory like you would do with a stream.
80 This allows the use of `cx_stream_copy()` (see [Utilities](#utilities)) to copy contents from one buffer to another,
81 or from a file or network streams to the buffer and vice-versa.
83 More features for convenient use of the buffer can be enabled, like automatic memory management and automatic
84 resizing of the buffer space.
86 Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative
87 to automatically resizing the buffer space.
88 Please refer to the API doc for the fields prefixed with `flush_` to learn more.
90 ## Memory Pool
92 *Header file:* [mempool.h](api/mempool_8h.html)
94 ### Basic Memory Pool
96 *Header file:* [basic_mempool.h](api/basic__mempool_8h.html)
98 ## Iterator
100 *Header file:* [iterator.h](api/iterator_8h.html)
102 ## Collection
104 *Header file:* [collection.h](api/collection_8h.html)
106 ## List
108 *Header file:* [list.h](api/list_8h.html)
110 ### Linked List
112 *Header file:* [linked_list.h](api/linked__list_8h.html)
114 ### Array List
116 *Header file:* [array_list.h](api/array__list_8h.html)
118 ## Map
120 *Header file:* [map.h](api/map_8h.html)
122 ### Hash Map
124 *Header file:* [hash_map.h](api/hash__map_8h.html)
126 ## Utilities
128 *Header file:* [utils.h](api/utils_8h.html)
130 UCX provides some utilities for routine tasks. Most of them are simple macros, like e.g. the `cx_for_n()` macro,
131 creating a `for` loop counting from zero to (n-1) which is extremely useful to traverse the indices of
132 an array.
134 But the most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
135 bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
136 fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
137 a UCX buffer or vice-versa.
139 The following example shows, how easy it is to read the contents of a file into a buffer:
140 ```c
141 FILE *inputfile = fopen(infilename, "r");
142 if (inputfile) {
143 CxBuffer fbuf;
144 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
145 cx_stream_copy(inputfile, &fbuf,
146 (cx_read_func) fread,
147 (cx_write_func) cxBufferWrite);
148 fclose(inputfile);
150 // ... do something meaningful with the contents ...
152 cxBufferDestroy(&fbuf);
153 } else {
154 perror("Error opening input file");
155 if (fout != stdout) {
156 fclose(fout);
157 }
158 }
159 ```
161 ### Printf Functions
163 *Header file:* [printf.h](api/printf_8h.html)
165 ### Compare Functions
167 *Header file:* [compare.h](api/compare_8h.html)