tal/link: new module for reference-count style coding for tal.
[ccan] / ccan / tal / link / link.h
1 /* Licensed under BSD-MIT - see LICENSE file for details */
2 #ifndef TAL_LINK_H
3 #define TAL_LINK_H
4 #include "config.h"
5 #include <ccan/tal/tal.h>
6
7 /**
8  * tal_linkable - set up a tal object to be linkable.
9  * @newobj - the newly allocated object (with a NULL parent)
10  *
11  * The object will be freed when @newobj is freed or the last talloc_link()
12  * is talloc_delink'ed.
13  *
14  * Returns @newobj or NULL (if an allocation fails).
15  *
16  * Example:
17  *      int *shared_count;
18  *
19  *      shared_count = tal_linkable(talz(NULL, int));
20  *      assert(shared_count);
21  */
22 #define tal_linkable(newobj) \
23         (tal_typeof(newobj) tal_linkable_((newobj)))
24
25 /**
26  * tal_link - add a(nother) link to a linkable object.
27  * @ctx - the context to link to (parent of the resulting link)
28  * @obj - the object previously made linkable with talloc_linked().
29  *
30  * If @ctx is non-NULL, the link will be a child of @ctx, and this freed
31  * when @ctx is.
32  *
33  * Returns NULL on failure (out of memory).
34  *
35  * Example:
36  *      void *my_ctx = NULL;
37  *
38  *      tal_link(my_ctx, shared_count);
39  */
40 #if HAVE_STATEMENT_EXPR
41 /* Weird macro avoids gcc's 'warning: value computed is not used'. */
42 #define tal_link(ctx, obj)                              \
43         ({ tal_typeof(obj) tal_link_((ctx), (obj)); })
44 #else
45 #define tal_link(ctx, obj)                              \
46         (tal_typeof(obj) tal_link_((ctx), (obj)))
47 #endif
48
49 /**
50  * tal_delink - explicitly remove a link from a linkable object.
51  * @ctx - the context to link to (parent of the resulting link)
52  * @obj - the object previously made linkable with talloc_linked().
53  *
54  * Explicitly remove a link: normally it is implied by freeing @ctx.
55  * Removing the last link frees the object.  If @obj is NULL, nothing
56  * is done.
57  *
58  * Example:
59  *      tal_delink(my_ctx, shared_count);
60  */
61 #define tal_delink(ctx, obj)                            \
62         tal_delink_((ctx), (obj))
63
64 /* Internal helpers. */
65 void *tal_linkable_(tal_t *newobj);
66 void *tal_link_(const tal_t *ctx, const tal_t *dest);
67 void tal_delink_(const tal_t *ctx, const tal_t *dest);
68
69 #endif /* TAL_LINK_H */