idtree: new module
[ccan] / ccan / idtree / idtree.h
1 #ifndef CCAN_IDTREE_H
2 #define CCAN_IDTREE_H
3 #include <stdbool.h>
4
5 /**
6  * idtree_new - create an idr_context
7  * @mem_ctx: talloc parent to allocate from (may be NULL).
8  *
9  * Allocate an empty id tree.  You can free it with talloc_free().
10  */
11 struct idtree *idtree_new(void *mem_ctx);
12
13 /**
14  * idtree_add - get lowest available id, and assign a pointer to it.
15  * @idtree: the tree to allocate from
16  * @ptr: the non-NULL pointer to associate with the id
17  * @limit: the maximum id to allocate (ie. INT_MAX means no limit).
18  *
19  * This returns a non-negative id number, or -1 if all are taken.
20  */
21 int idtree_add(struct idtree *idtree, const void *ptr, int limit);
22
23 /**
24  * idtree_add_above - get lowest available id, starting at a given value.
25  * @idtree: the tree to allocate from
26  * @ptr: the non-NULL pointer to associate with the id
27  * @starting_id: the minimum id value to consider.
28  * @limit: the maximum id to allocate (ie. INT_MAX means no limit).
29  *
30  * This returns a non-negative id number, or -1 if all are taken.
31  */
32 int idtree_add_above(struct idtree *idtree, const void *ptr,
33                      int starting_id, int limit);
34
35 /**
36  * idtree_lookup - look up a given id
37  * @idtree: the tree to look in
38  * @id: the id to look up
39  *
40  * Returns NULL if the value is not found, otherwise the pointer value
41  * set with the idtree_add()/idtree_add_above().
42  */
43 void *idtree_lookup(const struct idtree *idtree, int id);
44
45 /**
46  * idtree_remove - remove a given id.
47  * @idtree: the tree to remove from
48  * @id: the id to remove.
49  *
50  * Returns false if the id was not in the tree.
51  */
52 bool idtree_remove(struct idtree *idtree, int id);
53 #endif /* CCAN_IDTREE_H */