X-Git-Url: http://git.ozlabs.org/?p=ccan;a=blobdiff_plain;f=ccan%2Fidtree%2Fidtree.h;h=7e58aa56bac314672d475e9af6f757d1369a61fd;hp=a8f8719bc9e5bfe0bffc9eb856fe3883892c9b20;hb=926996e88c32445c874ff9c4f47f159db6b45995;hpb=184070eb4a4a2e130c0053eb82fd8c96a19e954f

diff --git a/ccan/idtree/idtree.h b/ccan/idtree/idtree.h
index a8f8719b..7e58aa56 100644
--- a/ccan/idtree/idtree.h
+++ b/ccan/idtree/idtree.h
@@ -1,3 +1,4 @@
+/* Licensed under GPLv2+ - see LICENSE file for details */
 #ifndef CCAN_IDTREE_H
 #define CCAN_IDTREE_H
 #include <stdbool.h>
@@ -7,6 +8,16 @@
  * @mem_ctx: talloc parent to allocate from (may be NULL).
  *
  * Allocate an empty id tree.  You can free it with talloc_free().
+ *
+ * Example:
+ *	static struct idtree *ids;
+ *
+ *	static void init(void)
+ *	{
+ *		ids = idtree_new(NULL);
+ *		if (!ids)
+ *			err(1, "Failed to allocate idtree");
+ *	}
  */
 struct idtree *idtree_new(void *mem_ctx);
 
@@ -17,6 +28,29 @@ struct idtree *idtree_new(void *mem_ctx);
  * @limit: the maximum id to allocate (ie. INT_MAX means no limit).
  *
  * This returns a non-negative id number, or -1 if all are taken.
+ *
+ * Example:
+ *	struct foo {
+ *		unsigned int id;
+ *		// ...
+ *	};
+ *
+ *	// Create a new foo, assigning an id.
+ *	static struct foo *new_foo(void)
+ *	{
+ *		int id;
+ *		struct foo *foo = malloc(sizeof(*foo));
+ *		if (!foo)
+ *			return NULL;
+ *
+ *		id = idtree_add(ids, foo, INT_MAX);
+ *		if (id < 0) {
+ *			free(foo);
+ *			return NULL;
+ *		}
+ *		foo->id = id;
+ *		return foo;
+ *	}
  */
 int idtree_add(struct idtree *idtree, const void *ptr, int limit);
 
@@ -27,7 +61,30 @@ int idtree_add(struct idtree *idtree, const void *ptr, int limit);
  * @starting_id: the minimum id value to consider.
  * @limit: the maximum id to allocate (ie. INT_MAX means no limit).
  *
- * This returns a non-negative id number, or -1 if all are taken.
+ * Example:
+ *	static int last_id = -1;
+ *
+ *	// Create a new foo, assigning a consecutive id.
+ *	// This maximizes the time before ids roll.
+ *	static struct foo *new_foo_inc_id(void)
+ *	{
+ *		int id;
+ *		struct foo *foo = malloc(sizeof(*foo));
+ *		if (!foo)
+ *			return NULL;
+ *
+ *		id = idtree_add_above(ids, foo, last_id+1, INT_MAX);
+ *		if (id < 0) {
+ *			id = idtree_add(ids, foo, INT_MAX);
+ *			if (id < 0) {
+ *				free(foo);
+ *				return NULL;
+ *			}
+ *		}
+ *		last_id = id;
+ *		foo->id = id;
+ *		return foo;
+ *	}
  */
 int idtree_add_above(struct idtree *idtree, const void *ptr,
 		     int starting_id, int limit);
@@ -39,6 +96,13 @@ int idtree_add_above(struct idtree *idtree, const void *ptr,
  *
  * Returns NULL if the value is not found, otherwise the pointer value
  * set with the idtree_add()/idtree_add_above().
+ *
+ * Example:
+ *	// Look up a foo for a given ID.
+ *	static struct foo *find_foo(unsigned int id)
+ *	{
+ *		return idtree_lookup(ids, id);
+ *	}
  */
 void *idtree_lookup(const struct idtree *idtree, int id);
 
@@ -48,6 +112,15 @@ void *idtree_lookup(const struct idtree *idtree, int id);
  * @id: the id to remove.
  *
  * Returns false if the id was not in the tree.
+ *
+ * Example:
+ *	// Look up a foo for a given ID.
+ *	static void free_foo(struct foo *foo)
+ *	{
+ *		bool exists = idtree_remove(ids, foo->id);
+ *		assert(exists);
+ *		free(foo);
+ *	}
  */
 bool idtree_remove(struct idtree *idtree, int id);
 #endif /* CCAN_IDTREE_H */