ucx/allocator.h@151f5345f303
ucx/allocator.h
Wed, 17 Jul 2013 20:03:01 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Wed, 17 Jul 2013 20:03:01 +0200
- changeset 118
- 151f5345f303
- parent 107
- 86b19c98b5fd
- child 120
- 8170f658f017
- permissions
- -rw-r--r--
documented allocator + some further documentation for sstr_t
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2013 Olaf Wintermann. All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * Allocator for custom memory management.
30 *
31 * An UCX allocator consists of a pointer to the memory area / pool and four
32 * function pointers to memory management functions operating on this memory
33 * area / pool. These functions shall behave equivalent to the standard libc
34 * functions <code>malloc(), calloc(), realloc()</code> and <code>free()</code>.
35 *
36 * The signature of the memory management functions is based on the signature
37 * of the respective libc function but each of them takes the pointer to the
38 * memory area / pool as first argument.
39 *
40 * As the pointer to the memory area / pool can be arbitrarily chosen, any data
41 * can be provided to the memory management functions. An UcxMempool is just
42 * one example.
43 *
44 * @see mempool.h
45 * @see UcxMap
46 *
47 * @file allocator.h
48 * @author Mike Becker
49 * @author Olaf Wintermann
50 */
52 #ifndef UCX_ALLOCATOR_H
53 #define UCX_ALLOCATOR_H
55 #include "ucx.h"
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
61 /**
62 * A function pointer to the allocators <code>malloc()</code> function.
63 * @see UcxAllocator
64 */
65 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
66 /**
67 * A function pointer to the allocators <code>calloc()</code> function.
68 * @see UcxAllocator
69 */
70 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
71 /**
72 * A function pointer to the allocators <code>realloc()</code> function.
73 * @see UcxAllocator
74 */
75 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
76 /**
77 * A function pointer to the allocators <code>free()</code> function.
78 * @see UcxAllocator
79 */
80 typedef void(*ucx_allocator_free)(void *pool, void *data);
82 /**
83 * UCX allocator data structure containing memory management functions.
84 */
85 typedef struct {
86 /** Pointer to an area of memory or a complex memory pool.
87 * This pointer will be passed to any memory management function as first
88 * argument.
89 */
90 void *pool;
91 /**
92 * The <code>malloc()</code> function for this allocator.
93 */
94 ucx_allocator_malloc malloc;
95 /**
96 * The <code>calloc()</code> function for this allocator.
97 */
98 ucx_allocator_calloc calloc;
99 /**
100 * The <code>realloc()</code> function for this allocator.
101 */
102 ucx_allocator_realloc realloc;
103 /**
104 * The <code>free()</code> function for this allocator.
105 */
106 ucx_allocator_free free;
107 } UcxAllocator;
109 /**
110 * Returns a pointer to the default allocator.
111 *
112 * The default allocator contains wrappers to the standard libc memory
113 * management functions. Use this function to get a pointer to a globally
114 * available allocator. You may also define an own UcxAllocator by assigning
115 * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable
116 * to any function that takes an UcxAllocator as argument. Note that using
117 * this function is the recommended way of passing a default allocator, thus
118 * it never runs out of scope.
119 *
120 * @return a pointer to the default allocator
121 *
122 * @see UCX_ALLOCATOR_DEFAULT
123 */
124 UcxAllocator *ucx_default_allocator();
126 /**
127 * A wrapper for the standard libc <code>malloc()</code> function.
128 * @param ignore ignored (may be used by allocators for pooled memory)
129 * @param n argument passed to <code>malloc()</code>
130 * @return return value of <code>malloc()</code>
131 */
132 void *ucx_default_malloc(void *ignore, size_t n);
133 /**
134 * A wrapper for the standard libc <code>calloc()</code> function.
135 * @param ignore ignored (may be used by allocators for pooled memory)
136 * @param n argument passed to <code>calloc()</code>
137 * @param size argument passed to <code>calloc()</code>
138 * @return return value of <code>calloc()</code>
139 */
140 void *ucx_default_calloc(void *ignore, size_t n, size_t size);
141 /**
142 * A wrapper for the standard libc <code>realloc()</code> function.
143 * @param ignore ignored (may be used by allocators for pooled memory)
144 * @param data argumend passed to <code>realloc()</code>
145 * @param n argument passed to <code>realloc()</code>
146 * @return return value of <code>realloc()</code>
147 */
148 void *ucx_default_realloc(void *ignore, void *data, size_t n);
149 /**
150 * A wrapper for the standard libc <code>free()</code> function.
151 * @param ignore ignored (may be used by allocators for pooled memory)
152 * @param data argument passed to <code>free()</code>
153 * @return return value of <code>free()</code>
154 */
155 void ucx_default_free(void *ignore, void *data);
157 /**
158 * Convenient macro for a default allocator <code>struct</code> definition.
159 */
160 #define UCX_ALLOCATOR_DEFAULT {NULL, \
161 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
162 ucx_default_free }
164 #ifdef __cplusplus
165 }
166 #endif
168 #endif /* UCX_ALLOCATOR_H */
