Mercurial > hg > dav / file comparison

comparison: ucx/allocator.h

ucx/allocator.h

changeset 5
88625853ae74
parent 1
1bcaac272cdf
child 17
11dffb40cd91
equal deleted inserted replaced
4:ae5a98f0545c 5:88625853ae74
1 #ifndef ALLOCATOR_H 1 /*
2 #define ALLOCATOR_H 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 */
51
52 #ifndef UCX_ALLOCATOR_H
53 #define UCX_ALLOCATOR_H
3 54
4 #include "ucx.h" 55 #include "ucx.h"
5 56
6 #ifdef __cplusplus 57 #ifdef __cplusplus
7 extern "C" { 58 extern "C" {
8 #endif 59 #endif
9 60
61 /**
62 * A function pointer to the allocators <code>malloc()</code> function.
63 * @see UcxAllocator
64 */
10 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n); 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 */
11 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size); 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 */
12 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n); 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);
13 81
82 /**
83 * UCX allocator data structure containing memory management functions.
84 */
14 typedef struct { 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 */
15 void *pool; 90 void *pool;
16 ucx_allocator_malloc malloc; 91 /**
17 ucx_allocator_calloc calloc; 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 */
18 ucx_allocator_realloc realloc; 102 ucx_allocator_realloc realloc;
103 /**
104 * The <code>free()</code> function for this allocator.
105 */
106 ucx_allocator_free free;
19 } UcxAllocator; 107 } UcxAllocator;
20 108
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();
125
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 */
21 void *ucx_default_malloc(void *ignore, size_t n); 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 */
22 void *ucx_default_calloc(void *ignore, size_t n, size_t size); 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 */
23 void *ucx_default_realloc(void *ignore, void *data, size_t n); 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 */
154 void ucx_default_free(void *ignore, void *data);
24 155
156 /**
157 * Convenient macro for a default allocator <code>struct</code> definition.
158 */
25 #define UCX_ALLOCATOR_DEFAULT {NULL, \ 159 #define UCX_ALLOCATOR_DEFAULT {NULL, \
26 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc} 160 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
161 ucx_default_free }
27 162
28 #ifdef __cplusplus 163 #ifdef __cplusplus
29 } 164 }
30 #endif 165 #endif
31 166
32 #endif /* ALLOCATOR_H */ 167 #endif /* UCX_ALLOCATOR_H */
33 168

Mercurial Repository: dav

mercurial