take: add labels when CCAN_TAKE_DEBUG set, return in taken_any().

[ccan] / ccan / tlist / tlist.h

diff --git a/ccan/tlist/tlist.h b/ccan/tlist/tlist.h
index 1ce0b85ed9f03c01333c8412c2d260541f8724cb..a99191a2e0ebd75e9b13145550ac90d0a859f72e 100644 (file)
--- a/ccan/tlist/tlist.h
+++ b/ccan/tlist/tlist.h
@@ -11,15 +11,16 @@
  *
  * This declares a structure "struct tlist_@suffix" to use for
  * lists containing this type.  The actual list can be accessed using
- * ".raw" or tlist_raw().
+ * ".raw" or tlist_raw().  For maximum portability, place tlists
+ * embedded in structures as the last member.
  *
  * Example:
  *     // Defines struct tlist_children
  *     TLIST_TYPE(children, struct child);
  *     struct parent {
  *             const char *name;
- *             struct tlist_children children;
  *             unsigned int num_children;
+ *             struct tlist_children children;
  *     };
  *
  *     struct child {
@@ -185,6 +186,8 @@
  * Example:
  *     struct child *first;
  *     first = tlist_top(&parent->children, list);
+ *     if (!first)
+ *             printf("Empty list!\n");
  */
 #define tlist_top(h, member)                                           \
        ((tcon_type((h), canary))                                       \
@@ -202,6 +205,8 @@
  * Example:
  *     struct child *last;
  *     last = tlist_tail(&parent->children, list);
+ *     if (!last)
+ *             printf("Empty list!\n");
  */
 #define tlist_tail(h, member)                                          \
        ((tcon_type((h), canary))                                       \
@@ -209,6 +214,30 @@
                    (char *)(&(h)->_tcon[0].canary->member) -           \
                    (char *)((h)->_tcon[0].canary)))
 
+/**
+ * tlist_next - get the next entry in a list
+ * @h: the tlist
+ * @n: the list element
+ * @member: the list_node member of the type
+ *
+ * Returns the element of list @h immediately after @n, or NULL, if @n
+ * is the last element in the list.
+ */
+#define tlist_next(h, n, member)                                       \
+       list_next(tlist_raw((h), (n)), (n), member)
+
+/**
+ * tlist_prev - get the previous entry in a list
+ * @h: the tlist
+ * @n: the list element
+ * @member: the list_node member of the type
+ *
+ * Returns the element of list @h immediately before @n, or NULL, if
+ * @n is the first element in the list.
+ */
+#define tlist_prev(h, n, member)                                       \
+       list_prev(tlist_raw((h), (n)), (n), member)
+
 /**
  * tlist_for_each - iterate through a list.
  * @h: the tlist