X-Git-Url: https://git.ozlabs.org/?a=blobdiff_plain;ds=sidebyside;f=ccan%2Ftal%2Ftal.h;h=28726c324cedd9ec4c150bcd02f369c6e6180905;hb=7ca46909f86e8bbad4e4bb19cac1a75d4ebf3df6;hp=d511e88aa7b637c7dc8d98b1cccf3ad923025c92;hpb=0e34459a02e2615f50bac2767c7dce6632470946;p=ccan diff --git a/ccan/tal/tal.h b/ccan/tal/tal.h index d511e88a..28726c32 100644 --- a/ccan/tal/tal.h +++ b/ccan/tal/tal.h @@ -5,6 +5,7 @@ #include #include #include +#include #include #include #include @@ -17,14 +18,33 @@ */ 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. * @type: the type to allocate. * - * Allocates a specific type, with a given parent context. + * 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) tal_arr((ctx), type, 1) +#define tal(ctx, type) \ + ((type *)tal_alloc_((ctx), sizeof(type), false, TAL_LABEL(type, ""))) /** * talz - zeroing allocator function @@ -32,8 +52,13 @@ 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) tal_arrz((ctx), type, 1) +#define talz(ctx, type) \ + ((type *)tal_alloc_((ctx), sizeof(type), true, TAL_LABEL(type, ""))) /** * tal_free - free a tal-allocated pointer. @@ -41,6 +66,11 @@ typedef void tal_t; * * This calls the destructors for p (if any), then does the same for all its * children (recursively) before finally freeing the memory. + * + * Note: errno is preserved by this call. + * + * Example: + * tal_free(p); */ void tal_free(const tal_t *p); @@ -49,29 +79,42 @@ 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_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)) + ((type *)tal_alloc_((ctx), tal_sizeof_(sizeof(type), (count)), false, \ + TAL_LABEL(type, "[]"))) /** * tal_arrz - allocate an array of zeroed objects. * @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)) + ((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. @@ -81,7 +124,7 @@ 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'. + * Note: weird macro avoids gcc's 'warning: value computed is not used'. */ #if HAVE_STATEMENT_EXPR #define tal_steal(ctx, ptr) \ @@ -140,28 +183,29 @@ tal_t *tal_next(const tal_t *root, const tal_t *prev); * tal_parent - get the parent of a tal object. * @ctx: The tal allocated object. * - * Returns the parent, which may be NULL. + * Returns the parent, which may be NULL. Returns NULL if @ctx is NULL. */ tal_t *tal_parent(const tal_t *ctx); /** * tal_memdup - duplicate memory. - * @ctx: NULL, or tal allocated object to be parent. + * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). * @p: the memory to copy * @n: the number of bytes. + * */ void *tal_memdup(const tal_t *ctx, const void *p, size_t n); /** - * tal_strdup - duplicate a string. - * @ctx: NULL, or tal allocated object to be parent. + * tal_strdup - duplicate a string + * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). * @p: the string to copy */ 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. + * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). * @p: the string to copy * @n: the maximum length to copy. * @@ -171,16 +215,22 @@ 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. + * @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. */ 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. + * @ctx: NULL, or tal allocated object to be parent (or TAL_TAKE). * @fmt: the printf-style format. * @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); @@ -227,6 +277,19 @@ void tal_dump(void); #endif /* Internal support functions */ +#ifndef TAL_LABEL +#ifdef CCAN_TAL_NO_LABELS +#define TAL_LABEL(type, arr) NULL +#else +#ifdef CCAN_TAL_DEBUG +#define TAL_LABEL(type, arr) \ + __FILE__ ":" stringify(__LINE__) ":" stringify(type) arr +#else +#define TAL_LABEL(type, arr) stringify(type) arr +#endif /* CCAN_TAL_DEBUG */ +#endif +#endif + #if HAVE_BUILTIN_CONSTANT_P #define TAL_IS_LITERAL(str) __builtin_constant_p(str) #else @@ -256,11 +319,11 @@ static inline size_t tal_sizeof_(size_t size, size_t count) #define tal_typeof(ptr) #endif -void *tal_alloc_(const tal_t *ctx, size_t bytes, bool clear); +void *tal_alloc_(const tal_t *ctx, size_t bytes, bool clear, 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));