112 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that |
112 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that |
113 * particular implementation. |
113 * particular implementation. |
114 * |
114 * |
115 * @param memory a pointer to the object to destruct |
115 * @param memory a pointer to the object to destruct |
116 */ |
116 */ |
117 typedef void (*cx_destructor_func)(void *memory) __attribute__((__nonnull__)); |
117 __attribute__((__nonnull__)) |
|
118 typedef void (*cx_destructor_func)(void *memory); |
118 |
119 |
119 /** |
120 /** |
120 * Function pointer type for destructor functions. |
121 * Function pointer type for destructor functions. |
121 * |
122 * |
122 * A destructor function deallocates possible contents and MAY free the memory |
123 * A destructor function deallocates possible contents and MAY free the memory |
125 * particular implementation. |
126 * particular implementation. |
126 * |
127 * |
127 * @param data an optional pointer to custom data |
128 * @param data an optional pointer to custom data |
128 * @param memory a pointer to the object to destruct |
129 * @param memory a pointer to the object to destruct |
129 */ |
130 */ |
|
131 __attribute__((__nonnull__(2))) |
130 typedef void (*cx_destructor_func2)( |
132 typedef void (*cx_destructor_func2)( |
131 void *data, |
133 void *data, |
132 void *memory |
134 void *memory |
133 ) __attribute__((__nonnull__(2))); |
135 ); |
134 |
136 |
135 /** |
137 /** |
136 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. |
138 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. |
137 * |
139 * |
138 * \par Error handling |
140 * \par Error handling |
140 * |
142 * |
141 * @param mem pointer to the pointer to allocated block |
143 * @param mem pointer to the pointer to allocated block |
142 * @param n the new size in bytes |
144 * @param n the new size in bytes |
143 * @return zero on success, non-zero on failure |
145 * @return zero on success, non-zero on failure |
144 */ |
146 */ |
|
147 __attribute__((__nonnull__)) |
145 int cx_reallocate( |
148 int cx_reallocate( |
146 void **mem, |
149 void **mem, |
147 size_t n |
150 size_t n |
148 ) |
151 ); |
149 __attribute__((__nonnull__)); |
|
150 |
152 |
151 /** |
153 /** |
152 * Allocate \p n bytes of memory. |
154 * Allocate \p n bytes of memory. |
153 * |
155 * |
154 * @param allocator the allocator |
156 * @param allocator the allocator |
155 * @param n the number of bytes |
157 * @param n the number of bytes |
156 * @return a pointer to the allocated memory |
158 * @return a pointer to the allocated memory |
157 */ |
159 */ |
|
160 __attribute__((__malloc__)) |
|
161 __attribute__((__alloc_size__(2))) |
158 void *cxMalloc( |
162 void *cxMalloc( |
159 CxAllocator const *allocator, |
163 const CxAllocator *allocator, |
160 size_t n |
164 size_t n |
161 ) |
165 ); |
162 __attribute__((__malloc__)) |
|
163 __attribute__((__alloc_size__(2))); |
|
164 |
166 |
165 /** |
167 /** |
166 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. |
168 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. |
167 * This function may return the same pointer that was passed to it, if moving the memory |
169 * This function may return the same pointer that was passed to it, if moving the memory |
168 * was not necessary. |
170 * was not necessary. |
172 * @param allocator the allocator |
174 * @param allocator the allocator |
173 * @param mem pointer to the previously allocated block |
175 * @param mem pointer to the previously allocated block |
174 * @param n the new size in bytes |
176 * @param n the new size in bytes |
175 * @return a pointer to the re-allocated memory |
177 * @return a pointer to the re-allocated memory |
176 */ |
178 */ |
|
179 __attribute__((__warn_unused_result__)) |
|
180 __attribute__((__alloc_size__(3))) |
177 void *cxRealloc( |
181 void *cxRealloc( |
178 CxAllocator const *allocator, |
182 const CxAllocator *allocator, |
179 void *mem, |
183 void *mem, |
180 size_t n |
184 size_t n |
181 ) |
185 ); |
182 __attribute__((__warn_unused_result__)) |
|
183 __attribute__((__alloc_size__(3))); |
|
184 |
186 |
185 /** |
187 /** |
186 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. |
188 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. |
187 * This function acts like cxRealloc() using the pointer pointed to by \p mem. |
189 * This function acts like cxRealloc() using the pointer pointed to by \p mem. |
188 * |
190 * |
194 * @param allocator the allocator |
196 * @param allocator the allocator |
195 * @param mem pointer to the pointer to allocated block |
197 * @param mem pointer to the pointer to allocated block |
196 * @param n the new size in bytes |
198 * @param n the new size in bytes |
197 * @return zero on success, non-zero on failure |
199 * @return zero on success, non-zero on failure |
198 */ |
200 */ |
|
201 __attribute__((__nonnull__)) |
199 int cxReallocate( |
202 int cxReallocate( |
200 CxAllocator const *allocator, |
203 const CxAllocator *allocator, |
201 void **mem, |
204 void **mem, |
202 size_t n |
205 size_t n |
203 ) |
206 ); |
204 __attribute__((__nonnull__)); |
|
205 |
207 |
206 /** |
208 /** |
207 * Allocate \p nelem elements of \p n bytes each, all initialized to zero. |
209 * Allocate \p nelem elements of \p n bytes each, all initialized to zero. |
208 * |
210 * |
209 * @param allocator the allocator |
211 * @param allocator the allocator |
210 * @param nelem the number of elements |
212 * @param nelem the number of elements |
211 * @param n the size of each element in bytes |
213 * @param n the size of each element in bytes |
212 * @return a pointer to the allocated memory |
214 * @return a pointer to the allocated memory |
213 */ |
215 */ |
|
216 __attribute__((__malloc__)) |
|
217 __attribute__((__alloc_size__(2, 3))) |
214 void *cxCalloc( |
218 void *cxCalloc( |
215 CxAllocator const *allocator, |
219 const CxAllocator *allocator, |
216 size_t nelem, |
220 size_t nelem, |
217 size_t n |
221 size_t n |
218 ) |
222 ); |
219 __attribute__((__malloc__)) |
|
220 __attribute__((__alloc_size__(2, 3))); |
|
221 |
223 |
222 /** |
224 /** |
223 * Free a block allocated by this allocator. |
225 * Free a block allocated by this allocator. |
224 * |
226 * |
225 * \note Freeing a block of a different allocator is undefined. |
227 * \note Freeing a block of a different allocator is undefined. |
226 * |
228 * |
227 * @param allocator the allocator |
229 * @param allocator the allocator |
228 * @param mem a pointer to the block to free |
230 * @param mem a pointer to the block to free |
229 */ |
231 */ |
|
232 __attribute__((__nonnull__)) |
230 void cxFree( |
233 void cxFree( |
231 CxAllocator const *allocator, |
234 const CxAllocator *allocator, |
232 void *mem |
235 void *mem |
233 ) |
236 ); |
234 __attribute__((__nonnull__)); |
|
235 |
237 |
236 #ifdef __cplusplus |
238 #ifdef __cplusplus |
237 } // extern "C" |
239 } // extern "C" |
238 #endif |
240 #endif |
239 |
241 |