Defines | |
#define | APR_RING_ENTRY(elem) |
#define | APR_RING_HEAD(head, elem) |
#define | APR_RING_SENTINEL(hp, elem, link) (struct elem *)((char *)(hp) - APR_OFFSETOF(struct elem, link)) |
#define | APR_RING_FIRST(hp) (hp)->next |
#define | APR_RING_LAST(hp) (hp)->prev |
#define | APR_RING_NEXT(ep, link) (ep)->link.next |
#define | APR_RING_PREV(ep, link) (ep)->link.prev |
#define | APR_RING_INIT(hp, elem, link) |
#define | APR_RING_EMPTY(hp, elem, link) (APR_RING_FIRST((hp)) == APR_RING_SENTINEL((hp), elem, link)) |
#define | APR_RING_ELEM_INIT(ep, link) |
#define | APR_RING_SPLICE_BEFORE(lep, ep1, epN, link) |
#define | APR_RING_SPLICE_AFTER(lep, ep1, epN, link) |
#define | APR_RING_INSERT_BEFORE(lep, nep, link) APR_RING_SPLICE_BEFORE((lep), (nep), (nep), link) |
#define | APR_RING_INSERT_AFTER(lep, nep, link) APR_RING_SPLICE_AFTER((lep), (nep), (nep), link) |
#define | APR_RING_SPLICE_HEAD(hp, ep1, epN, elem, link) |
#define | APR_RING_SPLICE_TAIL(hp, ep1, epN, elem, link) |
#define | APR_RING_INSERT_HEAD(hp, nep, elem, link) APR_RING_SPLICE_HEAD((hp), (nep), (nep), elem, link) |
#define | APR_RING_INSERT_TAIL(hp, nep, elem, link) APR_RING_SPLICE_TAIL((hp), (nep), (nep), elem, link) |
#define | APR_RING_CONCAT(h1, h2, elem, link) |
#define | APR_RING_PREPEND(h1, h2, elem, link) |
#define | APR_RING_UNSPLICE(ep1, epN, link) |
#define | APR_RING_REMOVE(ep, link) APR_RING_UNSPLICE((ep), (ep), link) |
#define | APR_RING_FOREACH(ep, hp, elem, link) |
#define | APR_RING_FOREACH_REVERSE(ep, hp, elem, link) |
#define | APR_RING_CHECK_ONE(msg, ptr) |
#define | APR_RING_CHECK(hp, elem, link, msg) |
#define | APR_RING_CHECK_CONSISTENCY(hp, elem, link) |
#define | APR_RING_CHECK_ELEM(ep, elem, link, msg) |
#define | APR_RING_CHECK_ELEM_CONSISTENCY(ep, elem, link) |
|
Dump all ring pointers to STDERR, starting with the head and looping all the way around the ring back to the head. Aborts if an inconsistency is found. (This is a no-op unless APR_RING_DEBUG is defined.)
|
|
Loops around a ring and checks all the pointers for consistency. Pops an assertion if any inconsistency is found. Same idea as APR_RING_CHECK() except that it's silent if all is well. (This is a no-op unless APR_RING_DEBUG is defined.)
|
|
Dump all ring pointers to STDERR, starting with the given element and looping all the way around the ring back to that element. Aborts if an inconsistency is found. (This is a no-op unless APR_RING_DEBUG is defined.)
|
|
Loops around a ring, starting with the given element, and checks all the pointers for consistency. Pops an assertion if any inconsistency is found. Same idea as APR_RING_CHECK_ELEM() except that it's silent if all is well. (This is a no-op unless APR_RING_DEBUG is defined.)
|
|
Print a single pointer value to STDERR (This is a no-op unless APR_RING_DEBUG is defined.)
|
|
Value: do { \ if (!APR_RING_EMPTY((h2), elem, link)) { \ APR_RING_SPLICE_BEFORE(APR_RING_SENTINEL((h1), elem, link), \ APR_RING_FIRST((h2)), \ APR_RING_LAST((h2)), link); \ APR_RING_INIT((h2), elem, link); \ } \ } while (0)
|
|
Value: do { \ APR_RING_NEXT((ep), link) = (ep); \ APR_RING_PREV((ep), link) = (ep); \ } while (0)
|
|
Determine if a ring is empty
|
|
Value: struct { \ struct elem *next; \ struct elem *prev; \ } A ring element struct is linked to the other elements in the ring through its ring entry field, e.g. struct my_element_t { APR_RING_ENTRY(my_element_t) link; int foo; char *bar; }; An element struct may be put on more than one ring if it has more than one APR_RING_ENTRY field. Each APR_RING_ENTRY has a corresponding APR_RING_HEAD declaration.
|
|
The first element of the ring
|
|
Value: for ((ep) = APR_RING_FIRST((hp)); \ (ep) != APR_RING_SENTINEL((hp), elem, link); \ (ep) = APR_RING_NEXT((ep), link))
|
|
Value: for ((ep) = APR_RING_LAST((hp)); \ (ep) != APR_RING_SENTINEL((hp), elem, link); \ (ep) = APR_RING_PREV((ep), link))
|
|
Value: struct head { \ struct elem *next; \ struct elem *prev; \ } Each ring is managed via its head, which is a struct declared like this: APR_RING_HEAD(my_ring_t, my_element_t); struct my_ring_t ring, *ringp; This struct looks just like the element link struct so that we can be sure that the typecasting games will work as expected. The first element in the ring is next after the head, and the last element is just before the head. |
|
Value: do { \ APR_RING_FIRST((hp)) = APR_RING_SENTINEL((hp), elem, link); \ APR_RING_LAST((hp)) = APR_RING_SENTINEL((hp), elem, link); \ } while (0)
|
|
Insert the element nep into the ring after element lep (..lep.. becomes ..lep..nep..)
|
|
Insert the element nep into the ring before element lep (..lep.. becomes ..nep..lep..)
|
|
Insert the element nep into the ring before the first element (..hp.. becomes ..hp..nep..)
|
|
Insert the element nep into the ring after the last element (..hp.. becomes ..nep..hp..)
|
|
The last element of the ring
|
|
The next element in the ring
|
|
Value: do { \ if (!APR_RING_EMPTY((h2), elem, link)) { \ APR_RING_SPLICE_AFTER(APR_RING_SENTINEL((h1), elem, link), \ APR_RING_FIRST((h2)), \ APR_RING_LAST((h2)), link); \ APR_RING_INIT((h2), elem, link); \ } \ } while (0)
|
|
The previous element in the ring
|
|
Remove a single element from a ring
|
|
The Ring Sentinel This is the magic pointer value that occurs before the first and after the last elements in the ring, computed from the address of the ring's head. The head itself isn't an element, but in order to get rid of all the special cases when dealing with the ends of the ring, we play typecasting games to make it look like one. Here is a diagram to illustrate the arrangements of the next and prev pointers of each element in a single ring. Note that they point to the start of each element, not to the APR_RING_ENTRY structure.
+->+------+<-+ +->+------+<-+ +->+------+<-+ | |struct| | | |struct| | | |struct| | / | elem | \/ | elem | \/ | elem | \ ... | | /\ | | /\ | | ... +------+ | | +------+ | | +------+ ...--|prev | | +--|ring | | +--|prev | | next|--+ | entry|--+ | next|--... +------+ +------+ +------+ | etc. | | etc. | | etc. | : : : : : : The APR_RING_HEAD is nothing but a bare APR_RING_ENTRY. The prev and next pointers in the first and last elements don't actually point to the head, they point to a phantom place called the sentinel. Its value is such that last->next->next == first because the offset from the sentinel to the head's next pointer is the same as the offset from the start of an element to its next pointer. This also works in the opposite direction.
last first +->+------+<-+ +->sentinel<-+ +->+------+<-+ | |struct| | | | | |struct| | / | elem | \/ \/ | elem | \ ... | | /\ /\ | | ... +------+ | | +------+ | | +------+ ...--|prev | | +--|ring | | +--|prev | | next|--+ | head|--+ | next|--... +------+ +------+ +------+ | etc. | | etc. | : : : : Note that the offset mentioned above is different for each kind of ring that the element may be on, and each kind of ring has a unique name for its APR_RING_ENTRY in each element, and has its own type for its APR_RING_HEAD. Note also that if the offset is non-zero (which is required if an element has more than one APR_RING_ENTRY), the unreality of the sentinel may have bad implications on very perverse implementations of C -- see the warning in APR_RING_ENTRY.
|
|
Value: do { \ APR_RING_PREV((ep1), link) = (lep); \ APR_RING_NEXT((epN), link) = APR_RING_NEXT((lep), link); \ APR_RING_PREV(APR_RING_NEXT((lep), link), link) = (epN); \ APR_RING_NEXT((lep), link) = (ep1); \ } while (0)
|
|
Value: do { \ APR_RING_NEXT((epN), link) = (lep); \ APR_RING_PREV((ep1), link) = APR_RING_PREV((lep), link); \ APR_RING_NEXT(APR_RING_PREV((lep), link), link) = (ep1); \ APR_RING_PREV((lep), link) = (epN); \ } while (0)
|
|
Value: APR_RING_SPLICE_AFTER(APR_RING_SENTINEL((hp), elem, link), \ (ep1), (epN), link)
|
|
Value: APR_RING_SPLICE_BEFORE(APR_RING_SENTINEL((hp), elem, link), \ (ep1), (epN), link)
|
|
Value: do { \ APR_RING_NEXT(APR_RING_PREV((ep1), link), link) = \ APR_RING_NEXT((epN), link); \ APR_RING_PREV(APR_RING_NEXT((epN), link), link) = \ APR_RING_PREV((ep1), link); \ } while (0)
|