src/cx/allocator.h

Thu, 16 Oct 2025 19:57:47 +0200

author
Mike Becker <universe@uap-core.de>
date
Thu, 16 Oct 2025 19:57:47 +0200
changeset 1426
3a89b31f0724
parent 1424
563033aa998c
permissions
-rw-r--r--

clean up header files and adds support for comparing arbitrary strings with string.h functions

391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
28 /**
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
29 * @file allocator.h
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
30 * Interface for custom allocators.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
31 */
391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
32
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
33 #ifndef UCX_ALLOCATOR_H
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 #define UCX_ALLOCATOR_H
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35
484
9e6900b1cf9d add common.h include to all other header files
Mike Becker <universe@uap-core.de>
parents: 465
diff changeset
36 #include "common.h"
391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37
415
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
38 #ifdef __cplusplus
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
39 extern "C" {
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
40 #endif
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
41
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
42 /**
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
43 * The class definition for an allocator.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
44 */
396
3539dd99ab92 make cx_allocator_class shared
Mike Becker <universe@uap-core.de>
parents: 394
diff changeset
45 typedef struct {
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
46 /**
465
1e3cb39815f8 remove redundant documentation for function pointers
Mike Becker <universe@uap-core.de>
parents: 461
diff changeset
47 * The allocator's malloc() implementation.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
48 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
49 void *(*malloc)(void *data, size_t n);
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
50
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
51 /**
465
1e3cb39815f8 remove redundant documentation for function pointers
Mike Becker <universe@uap-core.de>
parents: 461
diff changeset
52 * The allocator's realloc() implementation.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
53 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
54 void *(*realloc)(void *data, void *mem, size_t n);
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
55
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
56 /**
465
1e3cb39815f8 remove redundant documentation for function pointers
Mike Becker <universe@uap-core.de>
parents: 461
diff changeset
57 * The allocator's calloc() implementation.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
58 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
59 void *(*calloc)(void *data, size_t nmemb, size_t size);
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
60
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
61 /**
465
1e3cb39815f8 remove redundant documentation for function pointers
Mike Becker <universe@uap-core.de>
parents: 461
diff changeset
62 * The allocator's free() implementation.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
63 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
64 void (*free)(void *data, void *mem);
396
3539dd99ab92 make cx_allocator_class shared
Mike Becker <universe@uap-core.de>
parents: 394
diff changeset
65 } cx_allocator_class;
3539dd99ab92 make cx_allocator_class shared
Mike Becker <universe@uap-core.de>
parents: 394
diff changeset
66
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
67 /**
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
68 * Structure holding the data for an allocator.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
69 */
394
80c31ebd66c1 high level allocator functions should be real functions, not macros
Mike Becker <universe@uap-core.de>
parents: 393
diff changeset
70 struct cx_allocator_s {
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
71 /**
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
72 * A pointer to the instance of the allocator class.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
73 */
396
3539dd99ab92 make cx_allocator_class shared
Mike Becker <universe@uap-core.de>
parents: 394
diff changeset
74 cx_allocator_class *cl;
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
75 /**
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
76 * A pointer to the data this allocator uses.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
77 */
397
cfc1193b1e65 removes unnecessary cx_allocator typedef
Mike Becker <universe@uap-core.de>
parents: 396
diff changeset
78 void *data;
391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
79 };
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
80
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
81 /**
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
82 * High-Level type alias for the allocator type.
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
83 */
500
eb9e7bd40a8e do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents: 484
diff changeset
84 typedef struct cx_allocator_s CxAllocator;
391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
85
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
86 /**
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
87 * A pre-defined allocator using standard library malloc() etc.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
88 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
89 CX_EXPORT extern const CxAllocator * const cxStdlibAllocator;
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
90
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
91 /**
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
92 * The default allocator that is used by UCX.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
93 * Initialized with cxStdlibAllocator, but you may change it.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
94 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
95 CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
391
f094a53c1178 adds allocator interface and default implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
96
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
97 /**
503
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
98 * Function pointer type for destructor functions.
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
99 *
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
100 * A destructor function deallocates possible contents and MAY free the memory
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
101 * pointed to by @p memory. Read the documentation of the respective function
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
102 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
103 * that particular implementation.
503
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
104 *
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
105 * @param memory a pointer to the object to destruct
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
106 */
891
49d8cff6f0ee make all function attributes leading - fixes #425
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
107 typedef void (*cx_destructor_func)(void *memory);
503
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
108
a89857072ace add new destructor API and apply it to CxList
Mike Becker <universe@uap-core.de>
parents: 500
diff changeset
109 /**
528
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
110 * Function pointer type for destructor functions.
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
111 *
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
112 * A destructor function deallocates possible contents and MAY free the memory
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
113 * pointed to by @p memory. Read the documentation of the respective function
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
114 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
115 * that particular implementation.
528
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
116 *
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
117 * @param data an optional pointer to custom data
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
118 * @param memory a pointer to the object to destruct
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
119 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
120 typedef void (*cx_destructor_func2)(void *data, void *memory);
528
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
121
4fbfac557df8 #179 improve API for list content destruction
Mike Becker <universe@uap-core.de>
parents: 526
diff changeset
122 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
123 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
124 * if necessary.
726
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
125 *
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
126 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
127 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
128 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
129 * @c errno will be set by realloc() on failure.
726
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
130 *
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
131 * @param mem pointer to the pointer to allocated block
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
132 * @param n the new size in bytes
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
133 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
134 * @retval non-zero failure
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
135 * @see cx_reallocatearray()
726
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
136 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
137 cx_attr_nonnull cx_attr_nodiscard
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
138 CX_EXPORT int cx_reallocate_(
726
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
139 void **mem,
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
140 size_t n
891
49d8cff6f0ee make all function attributes leading - fixes #425
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
141 );
726
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
142
44986c0e2b05 add a low-level stdlib-based cx_reallocate()
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
143 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
144 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
145 * if necessary.
935
312fb24c14de add convenience macro for cx_reallocate to hide the (void**) cast
Mike Becker <universe@uap-core.de>
parents: 891
diff changeset
146 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
147 * The size is calculated by multiplying @p nemb and @p size.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
148 *
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
149 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
150 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
151 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
152 * @c errno will be set by realloc() on failure or when the multiplication of
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
153 * @p nmemb and @p size overflows.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
154 *
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
155 * @param mem pointer to the pointer to allocated block
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
156 * @param nmemb the number of elements
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
157 * @param size the size of each element
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
158 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
159 * @retval non-zero failure
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
160 * @see cx_reallocate()
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
161 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
162 cx_attr_nonnull cx_attr_nodiscard
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
163 CX_EXPORT int cx_reallocatearray_(void **mem, size_t nmemb, size_t size);
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
164
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
165 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
166 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
167 * if necessary.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
168 *
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
169 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
170 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
171 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
172 * @c errno will be set by realloc() on failure.
935
312fb24c14de add convenience macro for cx_reallocate to hide the (void**) cast
Mike Becker <universe@uap-core.de>
parents: 891
diff changeset
173 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
174 * @param mem (@c void**) pointer to the pointer to allocated block
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
175 * @param n (@c size_t) the new size in bytes
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
176 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
177 * @retval non-zero failure
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
178 * @see cx_reallocatearray()
935
312fb24c14de add convenience macro for cx_reallocate to hide the (void**) cast
Mike Becker <universe@uap-core.de>
parents: 891
diff changeset
179 */
1134
60edcd57d54c fix that some IDEs cannot resolve documentation
Mike Becker <universe@uap-core.de>
parents: 1087
diff changeset
180 #define cx_reallocate(mem, n) cx_reallocate_((void**)(mem), n)
935
312fb24c14de add convenience macro for cx_reallocate to hide the (void**) cast
Mike Becker <universe@uap-core.de>
parents: 891
diff changeset
181
312fb24c14de add convenience macro for cx_reallocate to hide the (void**) cast
Mike Becker <universe@uap-core.de>
parents: 891
diff changeset
182 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
183 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
184 * if necessary.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
185 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
186 * The size is calculated by multiplying @p nemb and @p size.
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
187 *
1318
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
188 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
12fa1d37fe48 allow changing the cxDefaultAllocator - resolves #669
Mike Becker <universe@uap-core.de>
parents: 1188
diff changeset
189 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
190 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
191 * @c errno will be set by realloc() on failure or when the multiplication of
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
192 * @p nmemb and @p size overflows.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
193 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
194 * @param mem (@c void**) pointer to the pointer to allocated block
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
195 * @param nmemb (@c size_t) the number of elements
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
196 * @param size (@c size_t) the size of each element
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
197 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
198 * @retval non-zero failure
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
199 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
200 #define cx_reallocatearray(mem, nmemb, size) \
1134
60edcd57d54c fix that some IDEs cannot resolve documentation
Mike Becker <universe@uap-core.de>
parents: 1087
diff changeset
201 cx_reallocatearray_((void**)(mem), nmemb, size)
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
202
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
203 /**
1330
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
204 * Allocates memory and sets every byte to zero.
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
205 *
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
206 * @param n (@c size_t) the number of bytes
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
207 * @return (@c void*) a pointer to the allocated memory
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
208 */
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
209 #define cx_zalloc(n) calloc(1, n)
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
210
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
211 /**
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
212 * Free a block allocated by this allocator.
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
213 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
214 * @note Freeing a block of a different allocator is undefined.
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
215 *
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
216 * @param allocator the allocator
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
217 * @param mem a pointer to the block to free
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
218 */
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
219 cx_attr_nonnull_arg(1)
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
220 CX_EXPORT void cxFree(const CxAllocator *allocator, void *mem);
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
221
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
222 /**
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
223 * Allocate @p n bytes of memory.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
224 *
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
225 * @param allocator the allocator
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
226 * @param n the number of bytes
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
227 * @return a pointer to the allocated memory
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
228 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
229 cx_attr_nodiscard cx_attr_nonnull
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
230 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
231 CX_EXPORT void *cxMalloc(const CxAllocator *allocator, size_t n);
397
cfc1193b1e65 removes unnecessary cx_allocator typedef
Mike Becker <universe@uap-core.de>
parents: 396
diff changeset
232
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
233 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
234 * Reallocate the previously allocated block in @p mem, making the new block
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
235 * @p n bytes long.
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1330
diff changeset
236 * This function may return the same pointer passed to it if moving
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
237 * the memory was not necessary.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
238 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
239 * @note Re-allocating a block allocated by a different allocator is undefined.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
240 *
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
241 * @param allocator the allocator
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
242 * @param mem pointer to the previously allocated block
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
243 * @param n the new size in bytes
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
244 * @return a pointer to the reallocated memory
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
245 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
246 cx_attr_nodiscard cx_attr_nonnull_arg(1)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
247 cx_attr_dealloc_ucx cx_attr_allocsize(3)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
248 CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
397
cfc1193b1e65 removes unnecessary cx_allocator typedef
Mike Becker <universe@uap-core.de>
parents: 396
diff changeset
249
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
250 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
251 * Reallocate the previously allocated block in @p mem, making the new block
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
252 * @p n bytes long.
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1330
diff changeset
253 * This function may return the same pointer passed to it if moving
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
254 * the memory was not necessary.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
255 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
256 * The size is calculated by multiplying @p nemb and @p size.
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1330
diff changeset
257 * If that multiplication overflows, this function returns @c NULL, and @c errno
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
258 * will be set.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
259 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
260 * @note Re-allocating a block allocated by a different allocator is undefined.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
261 *
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
262 * @param allocator the allocator
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
263 * @param mem pointer to the previously allocated block
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
264 * @param nmemb the number of elements
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
265 * @param size the size of each element
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
266 * @return a pointer to the reallocated memory
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
267 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
268 cx_attr_nodiscard cx_attr_nonnull_arg(1)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
269 cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
270 CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
271 void *mem, size_t nmemb, size_t size);
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
272
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
273 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
274 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
275 * if necessary.
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
276 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
277 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
278 * @note Re-allocating a block allocated by a different allocator is undefined.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
279 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
280 * @par Error handling
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1330
diff changeset
281 * @c errno will be set if the underlying realloc function does so.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
282 *
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
283 * @param allocator the allocator
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
284 * @param mem pointer to the pointer to allocated block
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
285 * @param n the new size in bytes
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
286 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
287 * @retval non-zero failure
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
288 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
289 cx_attr_nodiscard cx_attr_nonnull
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
290 CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
414
81a4c3a63e65 adds cxReallocate()
Mike Becker <universe@uap-core.de>
parents: 405
diff changeset
291
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
292 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
293 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
294 * if necessary.
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
295 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
296 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
297 * @note Re-allocating a block allocated by a different allocator is undefined.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
298 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
299 * @par Error handling
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1330
diff changeset
300 * @c errno will be set if the underlying realloc function does so.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
301 *
1087
128324af5164 don't document constness of arguments in macros
Mike Becker <universe@uap-core.de>
parents: 1085
diff changeset
302 * @param allocator (@c CxAllocator*) the allocator
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
303 * @param mem (@c void**) pointer to the pointer to allocated block
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
304 * @param n (@c size_t) the new size in bytes
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
305 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
306 * @retval non-zero failure
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
307 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
308 #define cxReallocate(allocator, mem, n) \
1134
60edcd57d54c fix that some IDEs cannot resolve documentation
Mike Becker <universe@uap-core.de>
parents: 1087
diff changeset
309 cxReallocate_(allocator, (void**)(mem), n)
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
310
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
311 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
312 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
313 * if necessary.
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
314 * This function acts like cxReallocArray() using the pointer pointed to
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
315 * by @p mem.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
316 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
317 * @note Re-allocating a block allocated by a different allocator is undefined.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
318 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
319 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
320 * @c errno will be set, if the underlying realloc function does so or the
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
321 * multiplication of @p nmemb and @p size overflows.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
322 *
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
323 * @param allocator the allocator
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
324 * @param mem pointer to the pointer to allocated block
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
325 * @param nmemb the number of elements
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
326 * @param size the size of each element
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
327 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
328 * @retval non-zero on failure
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
329 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
330 cx_attr_nodiscard cx_attr_nonnull
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
331 CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
332 void **mem, size_t nmemb, size_t size);
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
333
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
334 /**
1185
d825aca193d3 use reallocate instead of re-allocate
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
335 * Reallocate a previously allocated block and changes the pointer in-place,
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
336 * if necessary.
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 963
diff changeset
337 * This function acts like cxReallocArray() using the pointer pointed to
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
338 * by @p mem.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
339 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
340 * @note Re-allocating a block allocated by a different allocator is undefined.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
341 *
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
342 * @par Error handling
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
343 * @c errno will be set, if the underlying realloc function does so or the
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
344 * multiplication of @p nmemb and @p size overflows.
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
345 *
1087
128324af5164 don't document constness of arguments in macros
Mike Becker <universe@uap-core.de>
parents: 1085
diff changeset
346 * @param allocator (@c CxAllocator*) the allocator
1085
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
347 * @param mem (@c void**) pointer to the pointer to allocated block
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
348 * @param nmemb (@c size_t) the number of elements
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
349 * @param size (@c size_t) the size of each element
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
350 * @retval zero success
b8e0b4130cc3 refine docs for allocator.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
351 * @retval non-zero failure
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
352 */
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
353 #define cxReallocateArray(allocator, mem, nmemb, size) \
1134
60edcd57d54c fix that some IDEs cannot resolve documentation
Mike Becker <universe@uap-core.de>
parents: 1087
diff changeset
354 cxReallocateArray_(allocator, (void**) (mem), nmemb, size)
963
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
355
2f601274bbac add reallocarray() like functions - resolves #468
Mike Becker <universe@uap-core.de>
parents: 935
diff changeset
356 /**
1169
6a33a5648027 add documentation for allocator.h
Mike Becker <universe@uap-core.de>
parents: 1134
diff changeset
357 * Allocate @p nmemb elements of @p n bytes each, all initialized to zero.
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
358 *
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
359 * @param allocator the allocator
1169
6a33a5648027 add documentation for allocator.h
Mike Becker <universe@uap-core.de>
parents: 1134
diff changeset
360 * @param nmemb the number of elements
6a33a5648027 add documentation for allocator.h
Mike Becker <universe@uap-core.de>
parents: 1134
diff changeset
361 * @param size the size of each element in bytes
429
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
362 * @return a pointer to the allocated memory
3d8235c96a27 add documentation to allocator.h
Mike Becker <universe@uap-core.de>
parents: 419
diff changeset
363 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
364 cx_attr_nonnull_arg(1) cx_attr_nodiscard
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
365 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
366 CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
397
cfc1193b1e65 removes unnecessary cx_allocator typedef
Mike Becker <universe@uap-core.de>
parents: 396
diff changeset
367
1330
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
368 /**
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
369 * Allocate @p n bytes of memory and sets every byte to zero.
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
370 *
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
371 * @param allocator the allocator
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
372 * @param n the number of bytes
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
373 * @return a pointer to the allocated memory
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
374 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
375 cx_attr_nodiscard cx_attr_nonnull
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
376 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
377 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
1319
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
378
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
379 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
380 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
381 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
382 #define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
383 /**
1330
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
384 * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
385 */
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
386 #define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
dd5d2402d161 implement zalloc() - resolves #679
Mike Becker <universe@uap-core.de>
parents: 1319
diff changeset
387 /**
1319
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
388 * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
389 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
390 #define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
391 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
392 * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
393 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
394 #define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
395 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
396 * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
397 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
398 #define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
399 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
400 * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
401 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
402 #define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
403 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
404 * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
405 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
406 #define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
407 /**
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
408 * Convenience macro that invokes cxFree() with the cxDefaultAllocator.
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
409 */
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
410 #define cxFreeDefault(...) cxFree(cxDefaultAllocator, __VA_ARGS__)
aa1f580f8f59 add convenience macros for using the default allocator - relates to #669
Mike Becker <universe@uap-core.de>
parents: 1318
diff changeset
411
415
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
412 #ifdef __cplusplus
628
1e2be40f0cb5 use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents: 528
diff changeset
413 } // extern "C"
415
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
414 #endif
067aa769796a fix missing extern "C"
Mike Becker <universe@uap-core.de>
parents: 414
diff changeset
415
628
1e2be40f0cb5 use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents: 528
diff changeset
416 #endif // UCX_ALLOCATOR_H

mercurial