da71ca3f2f9f3f2b38dae2fb07c866b8833c8bad
[ccan] / ccan / tal / tal.h
1 /* Licensed under BSD-MIT - see LICENSE file for details */
2 #ifndef CCAN_TAL_H
3 #define CCAN_TAL_H
4 #include "config.h"
5 #include <ccan/compiler/compiler.h>
6 #include <ccan/likely/likely.h>
7 #include <ccan/typesafe_cb/typesafe_cb.h>
8 #include <ccan/str/str.h>
9 #include <stdlib.h>
10 #include <stdbool.h>
11 #include <stdarg.h>
12
13 /**
14  * tal_t - convenient alias for void to mark tal pointers.
15  *
16  * Since any pointer can be a tal-allocated pointer, it's often
17  * useful to use this typedef to mark them explicitly.
18  */
19 typedef void tal_t;
20
21 /**
22  * TAL_TAKE - fake tal_t to indicate function will own arguments.
23  *
24  * Various functions take a context on which to allocate: if you use
25  * TAL_TAKE there instead, it means that the argument(s) are actually
26  * tal objects.  The returned value will share the same parent; it may
27  * even be the same pointer as the arguments.  The arguments themselves
28  * will be reused, freed, or made a child of the return value: they are
29  * no longer valid for external use.
30  */
31 #define TAL_TAKE ((tal_t *)-2L)
32
33 /**
34  * tal - basic allocator function
35  * @ctx: NULL, or tal allocated object to be parent.
36  * @type: the type to allocate.
37  *
38  * Allocates a specific type, with a given parent context.  The name
39  * of the object is a string of the type, but if CCAN_TAL_DEBUG is
40  * defined it also contains the file and line which allocated it.
41  */
42 #define tal(ctx, type) \
43         ((type *)tal_alloc_((ctx), sizeof(type), false, TAL_LABEL(type, "")))
44
45 /**
46  * talz - zeroing allocator function
47  * @ctx: NULL, or tal allocated object to be parent.
48  * @type: the type to allocate.
49  *
50  * Equivalent to tal() followed by memset() to zero.
51  */
52 #define talz(ctx, type) \
53         ((type *)tal_alloc_((ctx), sizeof(type), true, TAL_LABEL(type, "")))
54
55 /**
56  * tal_free - free a tal-allocated pointer.
57  * @p: NULL, or tal allocated object to free.
58  *
59  * This calls the destructors for p (if any), then does the same for all its
60  * children (recursively) before finally freeing the memory.
61  */
62 void tal_free(const tal_t *p);
63
64 /**
65  * tal_arr - allocate an array of objects.
66  * @ctx: NULL, or tal allocated object to be parent.
67  * @type: the type to allocate.
68  * @count: the number to allocate.
69  */
70 #define tal_arr(ctx, type, count) \
71         ((type *)tal_alloc_((ctx), tal_sizeof_(sizeof(type), (count)), false, \
72                             TAL_LABEL(type, "[]")))
73
74 /**
75  * tal_arrz - allocate an array of zeroed objects.
76  * @ctx: NULL, or tal allocated object to be parent.
77  * @type: the type to allocate.
78  * @count: the number to allocate.
79  */
80 #define tal_arrz(ctx, type, count) \
81         ((type *)tal_alloc_((ctx), tal_sizeof_(sizeof(type), (count)), true, \
82                             TAL_LABEL(type, "[]")))
83
84 /**
85  * tal_resize - enlarge or reduce a tal_arr(z).
86  * @p: The tal allocated array to resize.
87  * @count: the number to allocate.
88  *
89  * This returns the new pointer, or NULL (and destroys the old one)
90  * on failure.
91  */
92 #define tal_resize(p, count) \
93         ((tal_typeof(p) tal_realloc_((p), tal_sizeof_(sizeof(*p), (count)))))
94
95 /**
96  * tal_steal - change the parent of a tal-allocated pointer.
97  * @ctx: The new parent.
98  * @ptr: The tal allocated object to move.
99  *
100  * This may need to perform an allocation, in which case it may fail; thus
101  * it can return NULL, otherwise returns @ptr.
102  *
103  * Weird macro avoids gcc's 'warning: value computed is not used'.
104  */
105 #if HAVE_STATEMENT_EXPR
106 #define tal_steal(ctx, ptr) \
107         ({ (tal_typeof(ptr) tal_steal_((ctx),(ptr))); })
108 #else
109 #define tal_steal(ctx, ptr) \
110         (tal_typeof(ptr) tal_steal_((ctx),(ptr)))
111 #endif
112
113 /**
114  * tal_add_destructor - add a callback function when this context is destroyed.
115  * @ptr: The tal allocated object.
116  * @function: the function to call before it's freed.
117  */
118 #define tal_add_destructor(ptr, function)                                     \
119         tal_add_destructor_((ptr), typesafe_cb(void, void *, (function), (ptr)))
120
121 /**
122  * tal_set_name - attach a name to a tal pointer.
123  * @ptr: The tal allocated object.
124  * @name: The name to use.
125  *
126  * The name is copied, unless we're certain it's a string literal.
127  */
128 #define tal_set_name(ptr, name)                               \
129     tal_set_name_((ptr), (name), TAL_IS_LITERAL(name))
130
131 /**
132  * tal_name - get the name for a tal pointer.
133  * @ptr: The tal allocated object.
134  *
135  * Returns NULL if no name has been set.
136  */
137 const char *tal_name(const tal_t *ptr);
138
139 /**
140  * tal_first - get the first tal object child.
141  * @root: The tal allocated object to start with, or NULL.
142  *
143  * Returns NULL if there are no children.
144  */
145 tal_t *tal_first(const tal_t *root);
146
147 /**
148  * tal_next - get the next tal object child.
149  * @root: The tal allocated object to start with, or NULL.
150  * @prev: The return value from tal_first or tal_next.
151  *
152  * Returns NULL if there are no more children.  This should be safe to
153  * call on an altering tree unless @prev is no longer a descendent of
154  * @root.
155  */
156 tal_t *tal_next(const tal_t *root, const tal_t *prev);
157
158 /**
159  * tal_parent - get the parent of a tal object.
160  * @ctx: The tal allocated object.
161  *
162  * Returns the parent, which may be NULL.
163  */
164 tal_t *tal_parent(const tal_t *ctx);
165
166 /**
167  * tal_memdup - duplicate memory.
168  * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE).
169  * @p: the memory to copy
170  * @n: the number of bytes.
171  *
172  */
173 void *tal_memdup(const tal_t *ctx, const void *p, size_t n);
174
175 /**
176  * tal_strdup - duplicate a string
177  * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE).
178  * @p: the string to copy
179  */
180 char *tal_strdup(const tal_t *ctx, const char *p);
181
182 /**
183  * tal_strndup - duplicate a limited amount of a string.
184  * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE).
185  * @p: the string to copy
186  * @n: the maximum length to copy.
187  *
188  * Always gives a nul-terminated string, with strlen() <= @n.
189  */
190 char *tal_strndup(const tal_t *ctx, const char *p, size_t n);
191
192 /**
193  * tal_asprintf - allocate a formatted string
194  * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE).
195  * @fmt: the printf-style format.
196  *
197  * If @ctx is TAL_TAKE, @fmt is freed and its parent will be the parent
198  * of the return value.
199  */
200 char *tal_asprintf(const tal_t *ctx, const char *fmt, ...) PRINTF_FMT(2,3);
201
202 /**
203  * tal_vasprintf - allocate a formatted string (va_list version)
204  * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE).
205  * @fmt: the printf-style format.
206  * @va: the va_list containing the format args.
207  *
208  * If @ctx is TAL_TAKE, @fmt is freed and its parent will be the parent
209  * of the return value.
210  */
211 char *tal_vasprintf(const tal_t *ctx, const char *fmt, va_list ap)
212         PRINTF_FMT(2,0);
213
214
215 /**
216  * tal_set_backend - set the allocation or error functions to use
217  * @alloc_fn: allocator or NULL (default is malloc)
218  * @resize_fn: re-allocator or NULL (default is realloc)
219  * @free_fn: free function or NULL (default is free)
220  * @error_fn: called on errors or NULL (default is abort)
221  *
222  * The defaults are set up so tal functions never return NULL, but you
223  * can override erorr_fn to change that.  error_fn can return, and is
224  * called if alloc_fn or resize_fn fail.
225  *
226  * If any parameter is NULL, that function is unchanged.
227  */
228 void tal_set_backend(void *(*alloc_fn)(size_t size),
229                      void *(*resize_fn)(void *, size_t size),
230                      void (*free_fn)(void *),
231                      void (*error_fn)(const char *msg));
232
233
234 /**
235  * tal_check - set the allocation or error functions to use
236  * @ctx: a tal context, or NULL.
237  * @errorstr: a string to prepend calls to error_fn, or NULL.
238  *
239  * This sanity-checks a tal tree (unless NDEBUG is defined, in which case
240  * it simply returns true).  If errorstr is not null, error_fn is called
241  * when a problem is found, otherwise it is not.
242  */
243 bool tal_check(const tal_t *ctx, const char *errorstr);
244
245 #ifdef CCAN_TAL_DEBUG
246 /**
247  * tal_dump - dump entire tal tree.
248  *
249  * This is a helper for debugging tal itself, which dumps all the tal internal
250  * state.
251  */
252 void tal_dump(void);
253 #endif
254
255 /* Internal support functions */
256 #ifndef TAL_LABEL
257 #ifdef CCAN_TAL_NO_LABELS
258 #define TAL_LABEL(type, arr) NULL
259 #else
260 #ifdef CCAN_TAL_DEBUG
261 #define TAL_LABEL(type, arr) \
262         __FILE__ ":" stringify(__LINE__) ":" stringify(type) arr
263 #else
264 #define TAL_LABEL(type, arr) stringify(type) arr
265 #endif /* CCAN_TAL_DEBUG */
266 #endif
267 #endif
268
269 #if HAVE_BUILTIN_CONSTANT_P
270 #define TAL_IS_LITERAL(str) __builtin_constant_p(str)
271 #else
272 #define TAL_IS_LITERAL(str) (sizeof(&*(str)) != sizeof(char *))
273 #endif
274
275 bool tal_set_name_(tal_t *ctx, const char *name, bool literal);
276
277 static inline size_t tal_sizeof_(size_t size, size_t count)
278 {
279         /* Multiplication wrap */
280         if (count && unlikely(size * count / size != count))
281                 return (size_t)-1024;
282
283         size *= count;
284
285         /* Make sure we don't wrap adding header. */
286         if (size > (size_t)-1024)
287                 return (size_t)-1024;
288
289         return size;
290 }
291
292 #if HAVE_TYPEOF
293 #define tal_typeof(ptr) (__typeof__(ptr))
294 #else
295 #define tal_typeof(ptr)
296 #endif
297
298 void *tal_alloc_(const tal_t *ctx, size_t bytes, bool clear, const char *label);
299
300 tal_t *tal_steal_(const tal_t *new_parent, const tal_t *t);
301
302 void *tal_realloc_(tal_t *ctx, size_t size);
303
304 bool tal_add_destructor_(tal_t *ctx, void (*destroy)(void *me));
305
306 #endif /* CCAN_TAL_H */