X-Git-Url: http://git.ozlabs.org/?p=ccan;a=blobdiff_plain;f=ccan%2Ftal%2Ftal.h;h=8ee27c36ed1dce69e45d40187f976b23292712a2;hp=da448d8f22ad8813520299546a51ce09c0a00705;hb=d73a2bcb320a016aa74262991cfd7685dc132056;hpb=dfe59969500a0c4e3b82ce6e7f8227d1a6e7b178 diff --git a/ccan/tal/tal.h b/ccan/tal/tal.h index da448d8f..8ee27c36 100644 --- a/ccan/tal/tal.h +++ b/ccan/tal/tal.h @@ -18,18 +18,6 @@ */ typedef void tal_t; -/** - * TAL_TAKE - fake tal_t to indicate function will own arguments. - * - * Various functions take a context on which to allocate: if you use - * TAL_TAKE there instead, it means that the argument(s) are actually - * tal objects. The returned value will share the same parent; it may - * even be the same pointer as the arguments. The arguments themselves - * will be reused, freed, or made a child of the return value: they are - * no longer valid for external use. - */ -#define TAL_TAKE ((tal_t *)-2L) - /** * tal - basic allocator function * @ctx: NULL, or tal allocated object to be parent. @@ -38,6 +26,10 @@ typedef void tal_t; * Allocates a specific type, with a given parent context. The name * of the object is a string of the type, but if CCAN_TAL_DEBUG is * defined it also contains the file and line which allocated it. + * + * Example: + * int *p = tal(NULL, int); + * *p = 1; */ #define tal(ctx, type) \ ((type *)tal_alloc_((ctx), sizeof(type), false, TAL_LABEL(type, ""))) @@ -48,6 +40,10 @@ typedef void tal_t; * @type: the type to allocate. * * Equivalent to tal() followed by memset() to zero. + * + * Example: + * p = talz(NULL, int); + * assert(*p == 0); */ #define talz(ctx, type) \ ((type *)tal_alloc_((ctx), sizeof(type), true, TAL_LABEL(type, ""))) @@ -57,15 +53,26 @@ typedef void tal_t; * @p: NULL, or tal allocated object to free. * * This calls the destructors for p (if any), then does the same for all its - * children (recursively) before finally freeing the memory. + * children (recursively) before finally freeing the memory. It returns + * NULL, for convenience. + * + * Note: errno is preserved by this call. + * + * Example: + * p = tal_free(p); */ -void tal_free(const tal_t *p); +void *tal_free(const tal_t *p); /** * tal_arr - allocate an array of objects. * @ctx: NULL, or tal allocated object to be parent. * @type: the type to allocate. * @count: the number to allocate. + * + * Example: + * p = tal_arr(NULL, int, 2); + * p[0] = 0; + * p[1] = 1; */ #define tal_arr(ctx, type, count) \ ((type *)tal_alloc_((ctx), tal_sizeof_(sizeof(type), (count)), false, \ @@ -76,21 +83,27 @@ void tal_free(const tal_t *p); * @ctx: NULL, or tal allocated object to be parent. * @type: the type to allocate. * @count: the number to allocate. + * + * Example: + * p = tal_arrz(NULL, int, 2); + * assert(p[0] == 0 && p[1] == 0); */ #define tal_arrz(ctx, type, count) \ ((type *)tal_alloc_((ctx), tal_sizeof_(sizeof(type), (count)), true, \ TAL_LABEL(type, "[]"))) /** - * tal_resize - enlarge or reduce a tal_arr(z). - * @p: The tal allocated array to resize. + * tal_resize - enlarge or reduce a tal_arr[z]. + * @p: A pointer to the tal allocated array to resize. * @count: the number to allocate. * - * This returns the new pointer, or NULL (and destroys the old one) - * on failure. + * This returns true on success (and may move *@p), or false on failure. + * + * Example: + * tal_resize(&p, 100); */ #define tal_resize(p, count) \ - ((tal_typeof(p) tal_realloc_((p), tal_sizeof_(sizeof(*p), (count))))) + tal_resize_((void **)(p), tal_sizeof_(sizeof**(p), (count))) /** * tal_steal - change the parent of a tal-allocated pointer. @@ -99,10 +112,9 @@ void tal_free(const tal_t *p); * * This may need to perform an allocation, in which case it may fail; thus * it can return NULL, otherwise returns @ptr. - * - * Weird macro avoids gcc's 'warning: value computed is not used'. */ #if HAVE_STATEMENT_EXPR +/* Weird macro avoids gcc's 'warning: value computed is not used'. */ #define tal_steal(ctx, ptr) \ ({ (tal_typeof(ptr) tal_steal_((ctx),(ptr))); }) #else @@ -114,10 +126,88 @@ void tal_free(const tal_t *p); * tal_add_destructor - add a callback function when this context is destroyed. * @ptr: The tal allocated object. * @function: the function to call before it's freed. + * + * Note that this can only fail if your allocfn fails and your errorfn returns. */ #define tal_add_destructor(ptr, function) \ tal_add_destructor_((ptr), typesafe_cb(void, void *, (function), (ptr))) +/** + * tal_del_destructor - remove a destructor callback function. + * @ptr: The tal allocated object. + * @function: the function to call before it's freed. + * + * If @function has not been successfully added as a destructor, this returns + * false. + */ +#define tal_del_destructor(ptr, function) \ + tal_del_destructor_((ptr), typesafe_cb(void, void *, (function), (ptr))) + +enum tal_notify_type { + TAL_NOTIFY_FREE = 1, + TAL_NOTIFY_STEAL = 2, + TAL_NOTIFY_MOVE = 4, + TAL_NOTIFY_RESIZE = 8, + TAL_NOTIFY_RENAME = 16, + TAL_NOTIFY_ADD_CHILD = 32, + TAL_NOTIFY_DEL_CHILD = 64, + TAL_NOTIFY_ADD_NOTIFIER = 128, + TAL_NOTIFY_DEL_NOTIFIER = 256 +}; + +/** + * tal_add_notifier - add a callback function when this context changes. + * @ptr: The tal allocated object. + * @types: Bitwise OR of the types the callback is interested in. + * @callback: the function to call. + * + * Note that this can only fail if your allocfn fails and your errorfn + * returns. Also note that notifiers are not reliable in the case + * where an allocation fails, as they may be called before any + * allocation is actually done. + * + * TAL_NOTIFY_FREE is called when @ptr is freed, either directly or + * because an ancestor is freed: @info is the argument to tal_free(). + * It is exactly equivalent to a destructor, with more information. + * + * TAL_NOTIFY_STEAL is called when @ptr's parent changes: @info is the + * new parent. + * + * TAL_NOTIFY_MOVE is called when @ptr is realloced (via tal_resize) + * and moved. In this case, @ptr arg here is the new memory, and + * @info is the old pointer. + * + * TAL_NOTIFY_RESIZE is called when @ptr is realloced via tal_resize: + * @info is the new size, in bytes. If the pointer has moved, + * TAL_NOTIFY_MOVE callbacks are called first. + * + * TAL_NOTIFY_ADD_CHILD/TAL_NOTIFY_DEL_CHILD are called when @ptr is + * the context for a tal() allocating call, or a direct child is + * tal_free()d: @info is the child. Note that TAL_NOTIFY_DEL_CHILD is + * not called when this context is tal_free()d: TAL_NOTIFY_FREE is + * considered sufficient for that case. + * + * TAL_NOTIFY_ADD_NOTIFIER/TAL_NOTIFIER_DEL_NOTIFIER are called when + * a notifier is added or removed (not for this notifier): @info is the + * callback. + */ +#define tal_add_notifier(ptr, types, callback) \ + tal_add_notifier_((ptr), (types), \ + typesafe_cb_postargs(void, tal_t *, (callback), \ + (ptr), \ + enum tal_notify_type, void *)) + +/** + * tal_del_notifier - remove a notifier callback function. + * @ptr: The tal allocated object. + * @callback: the function to call. + */ +#define tal_del_notifier(ptr, callback) \ + tal_del_notifier_((ptr), \ + typesafe_cb_postargs(void, void *, (callback), \ + (ptr), \ + enum tal_notify_type, void *)) + /** * tal_set_name - attach a name to a tal pointer. * @ptr: The tal allocated object. @@ -164,25 +254,30 @@ tal_t *tal_next(const tal_t *root, const tal_t *prev); tal_t *tal_parent(const tal_t *ctx); /** - * tal_memdup - duplicate memory. - * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). - * @p: the memory to copy - * @n: the number of bytes. - * + * tal_dup - duplicate an array. + * @ctx: The tal allocated object to be parent of the result (may be NULL). + * @type: the type (should match type of @p!) + * @p: the array to copy (or resized & reparented if take()) + * @n: the number of sizeof(type) entries to copy. + * @extra: the number of extra sizeof(type) entries to allocate. */ -void *tal_memdup(const tal_t *ctx, const void *p, size_t n); +#define tal_dup(ctx, type, p, n, extra) \ + ((type *)tal_dup_((ctx), tal_typechk_(p, type *), \ + tal_sizeof_(sizeof(type), (n)), \ + tal_sizeof_(sizeof(type), (extra)), \ + TAL_LABEL(type, "[]"))) /** * tal_strdup - duplicate a string - * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). - * @p: the string to copy + * @ctx: NULL, or tal allocated object to be parent. + * @p: the string to copy (can be take()). */ char *tal_strdup(const tal_t *ctx, const char *p); /** * tal_strndup - duplicate a limited amount of a string. - * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). - * @p: the string to copy + * @ctx: NULL, or tal allocated object to be parent. + * @p: the string to copy (can be take()). * @n: the maximum length to copy. * * Always gives a nul-terminated string, with strlen() <= @n. @@ -191,22 +286,16 @@ char *tal_strndup(const tal_t *ctx, const char *p, size_t n); /** * tal_asprintf - allocate a formatted string - * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). - * @fmt: the printf-style format. - * - * If @ctx is TAL_TAKE, @fmt is freed and its parent will be the parent - * of the return value. + * @ctx: NULL, or tal allocated object to be parent. + * @fmt: the printf-style format (can be take()). */ char *tal_asprintf(const tal_t *ctx, const char *fmt, ...) PRINTF_FMT(2,3); /** * tal_vasprintf - allocate a formatted string (va_list version) - * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). - * @fmt: the printf-style format. + * @ctx: NULL, or tal allocated object to be parent. + * @fmt: the printf-style format (can be take()). * @va: the va_list containing the format args. - * - * If @ctx is TAL_TAKE, @fmt is freed and its parent will be the parent - * of the return value. */ char *tal_vasprintf(const tal_t *ctx, const char *fmt, va_list ap) PRINTF_FMT(2,0); @@ -291,16 +380,34 @@ static inline size_t tal_sizeof_(size_t size, size_t count) #if HAVE_TYPEOF #define tal_typeof(ptr) (__typeof__(ptr)) +#if HAVE_STATEMENT_EXPR +/* Careful: ptr can be const foo *, ptype is foo *. Also, ptr could + * be an array, eg "hello". */ +#define tal_typechk_(ptr, ptype) ({ __typeof__((ptr)+0) _p = (ptype)(ptr); _p; }) #else +#define tal_typechk_(ptr, ptype) (ptr) +#endif +#else /* !HAVE_TYPEOF */ #define tal_typeof(ptr) +#define tal_typechk_(ptr, ptype) (ptr) #endif void *tal_alloc_(const tal_t *ctx, size_t bytes, bool clear, const char *label); +void *tal_dup_(const tal_t *ctx, const void *p, size_t n, size_t extra, + const char *label); + tal_t *tal_steal_(const tal_t *new_parent, const tal_t *t); -void *tal_realloc_(tal_t *ctx, size_t size); +bool tal_resize_(tal_t **ctxp, size_t size); bool tal_add_destructor_(tal_t *ctx, void (*destroy)(void *me)); - +bool tal_del_destructor_(tal_t *ctx, void (*destroy)(void *me)); + +bool tal_add_notifier_(tal_t *ctx, enum tal_notify_type types, + void (*notify)(tal_t *ctx, enum tal_notify_type, + void *info)); +bool tal_del_notifier_(tal_t *ctx, + void (*notify)(tal_t *ctx, enum tal_notify_type, + void *info)); #endif /* CCAN_TAL_H */