apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jwool...@apache.org
Subject cvs commit: apr-util/include apr_ring.h
Date Sun, 18 Feb 2001 00:10:54 GMT
jwoolley    01/02/17 16:10:54

  Modified:    include  apr_ring.h
  Log:
  Add documentation to all of the RING macros.
  
  Revision  Changes    Path
  1.8       +258 -52   apr-util/include/apr_ring.h
  
  Index: apr_ring.h
  ===================================================================
  RCS file: /home/cvs/apr-util/include/apr_ring.h,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -d -u -r1.7 -r1.8
  --- apr_ring.h	2001/02/16 04:17:10	1.7
  +++ apr_ring.h	2001/02/18 00:10:52	1.8
  @@ -70,23 +70,34 @@
    */
   #include <stddef.h>
   
  +/**
  + * @package Rings
  + */
   /*
    * A ring is a kind of doubly-linked list that can be manipulated
    * without knowing where its head is.
    */
   
  -/*
  - * A struct on a ring contains a field linking it to the other
  - * elements in the ring, e.g.
  +/**
  + * <p>The Ring Element</p>
    *
  - *      struct my_item_t {
  - *          APR_RING_ENTRY(my_item_t) link;
  + * A ring element struct is linked to the other elements in the ring
  + * through its ring entry field, e.g.
  + * <pre>
  + *      struct my_element_t {
  + *          APR_RING_ENTRY(my_element_t) link;
    *          int foo;
    *          char *bar;
    *      };
  + * </pre>
  + * An element struct may be put on more than one ring if it has
  + * more than one APR_RING_ENTRY field.
    *
  - * A struct may be put on more than one ring if it has more than one
  - * APR_RING_ENTRY field.
  + * @warning For strict C standards compliance you should put the APR_RING_ENTRY
  + * first in the element struct unless the head is always part of a larger
  + * object with enough earlier fields to accommodate the offsetof() used
  + * to compute the ring sentinel below. You can usually ignore this caveat.
  + * @defvar APR_RING_ENTRY
    */
   #define APR_RING_ENTRY(elem)						\
       struct {								\
  @@ -94,17 +105,21 @@
   	struct elem *prev;						\
       }
   
  -/*
  - * Each ring is managed via its head, which is a struct declared like this:
  +/**
  + * <p>The Ring Head</p>
    *
  - *      APR_RING_HEAD(my_ring_t, my_item_t);
  + * Each ring is managed via its head, which is a struct declared like this:
  + * <pre>
  + *      APR_RING_HEAD(my_ring_t, my_element_t);
    *      struct my_ring_t ring, *ringp;
  + * </pre>
    *
    * 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.
  + * @defvar APR_RING_HEAD
    */
   #define APR_RING_HEAD(head, elem)					\
       struct head {							\
  @@ -112,93 +127,211 @@
   	struct elem *prev;						\
       }
   
  -/*
  - * 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. The sentinel 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.
  +/**
  + * <p>The Ring Sentinel</p>
    *
  - * Note that for strict C standards compliance you should put the
  - * APR_RING_ENTRY first in struct elem unless the head is always part
  - * of a larger object with enough earlier fields to accommodate the
  - * offsetof() computed below. You can usually ignore this caveat.
  + * 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.
  + *
  + * @param hp   The head of the ring
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc elem *APR_RING_SENTINEL(head *hp, struct elem, APR_RING_ENTRY link)
    */
   #define APR_RING_SENTINEL(hp, elem, link)				\
       (struct elem *)((char *)(hp) - offsetof(struct elem, link))
   
  -/*
  - * Accessor macros. Use these rather than footling inside the
  - * structures directly so that you can more easily change to a
  - * different flavour of list from BSD's <sys/queue.h>.
  +/**
  + * The first element of the ring
  + * @param hp   The head of the ring
  + * @deffunc elem *APR_RING_FIRST(head *hp)
    */
   #define APR_RING_FIRST(hp)	(hp)->next
  +/**
  + * The last element of the ring
  + * @param hp   The head of the ring
  + * @deffunc elem *APR_RING_LAST(head *hp)
  + */
   #define APR_RING_LAST(hp)	(hp)->prev
  +/**
  + * The next element in the ring
  + * @param ep   The current element
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc elem *APR_RING_NEXT(elem *ep, APR_RING_ENTRY link)
  + */
   #define APR_RING_NEXT(ep, link)	(ep)->link.next
  +/**
  + * The previous element in the ring
  + * @param ep   The current element
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc elem *APR_RING_PREV(elem *ep, APR_RING_ENTRY link)
  + */
   #define APR_RING_PREV(ep, link)	(ep)->link.prev
   
  -/*
  - * Empty rings and singleton elements.
  +
  +/**
  + * Initialize a ring
  + * @param hp   The head of the ring
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_INIT(head *hp, struct elem, APR_RING_ENTRY link)
    */
   #define APR_RING_INIT(hp, elem, link) do {				\
   	APR_RING_FIRST((hp)) = APR_RING_SENTINEL((hp), elem, link);	\
   	APR_RING_LAST((hp))  = APR_RING_SENTINEL((hp), elem, link);	\
       } while (0)
   
  +/**
  + * Determine if a ring is empty
  + * @param hp   The head of the ring
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @return true or false
  + * @deffunc int APR_RING_EMPTY(head *hp, struct elem, APR_RING_ENTRY link)
  + */
   #define APR_RING_EMPTY(hp, elem, link)					\
       (APR_RING_FIRST((hp)) == APR_RING_SENTINEL((hp), elem, link))
   
  +/**
  + * Initialize a singleton element
  + * @param ep   The element
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_ELEM_INIT(elem *ep, APR_RING_ENTRY link)
  + */
   #define APR_RING_ELEM_INIT(ep, link) do {				\
   	APR_RING_NEXT((ep), link) = (ep);				\
   	APR_RING_PREV((ep), link) = (ep);				\
       } while (0)
   
  -/*
  - * Adding elements.
  +
  +/**
  + * Splice the sequence ep1..epN into the ring before element lep
  + *   (..lep.. becomes ..ep1..epN..lep..)
  + * @warning This doesn't work for splicing before the first element or on
  + *   empty rings... see APR_RING_SPLICE_HEAD for one that does
  + * @param lep  Element in the ring to splice before
  + * @param ep1  First element in the sequence to splice in
  + * @param epN  Last element in the sequence to splice in
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_SPLICE_BEFORE(elem *lep, elem *ep1, elem *epN, APR_RING_ENTRY
link)
    */
  -#define APR_RING_SPLICE_BEFORE(lep, ep1, epN, link) do {			\
  +#define APR_RING_SPLICE_BEFORE(lep, ep1, epN, link) 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((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)
   
  +/**
  + * Splice the sequence ep1..epN into the ring after element lep
  + *   (..lep.. becomes ..lep..ep1..epN..)
  + * @warning This doesn't work for splicing after the last element or on
  + *   empty rings... see APR_RING_SPLICE_TAIL for one that does
  + * @param lep  Element in the ring to splice after
  + * @param ep1  First element in the sequence to splice in
  + * @param epN  Last element in the sequence to splice in
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_SPLICE_AFTER(elem *lep, elem *ep1, elem *epN, APR_RING_ENTRY
link)
  + */
   #define APR_RING_SPLICE_AFTER(lep, ep1, epN, link) 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((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)
   
  +/**
  + * Insert the element nep into the ring before element lep
  + *   (..lep.. becomes ..nep..lep..)
  + * @warning This doesn't work for inserting before the first element or on
  + *   empty rings... see APR_RING_INSERT_HEAD for one that does
  + * @param lep  Element in the ring to insert before
  + * @param nep  Element to insert
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_INSERT_BEFORE(elem *lep, elem *nep, APR_RING_ENTRY link)
  + */
   #define APR_RING_INSERT_BEFORE(lep, nep, link)				\
   	APR_RING_SPLICE_BEFORE((lep), (nep), (nep), link)
   
  +/**
  + * Insert the element nep into the ring after element lep
  + *   (..lep.. becomes ..lep..nep..)
  + * @warning This doesn't work for inserting after the last element or on
  + *   empty rings... see APR_RING_INSERT_TAIL for one that does
  + * @param lep  Element in the ring to insert after
  + * @param nep  Element to insert
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_INSERT_AFTER(elem *lep, elem *nep, APR_RING_ENTRY link)
  + */
   #define APR_RING_INSERT_AFTER(lep, nep, link)				\
   	APR_RING_SPLICE_AFTER((lep), (nep), (nep), link)
   
  -/*
  - * These macros work when the ring is empty: inserting before the head
  - * or after the tail of an empty ring using the macros above doesn't work.
  +
  +/**
  + * Splice the sequence ep1..epN into the ring before the first element
  + *   (..hp.. becomes ..hp..ep1..epN..)
  + * @param hp   Head of the ring
  + * @param ep1  First element in the sequence to splice in
  + * @param epN  Last element in the sequence to splice in
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_SPLICE_HEAD(head *hp, elem *ep1, elem *epN, struct elem, APR_RING_ENTRY
link)
    */
   #define APR_RING_SPLICE_HEAD(hp, ep1, epN, elem, link)			\
   	APR_RING_SPLICE_AFTER(APR_RING_SENTINEL((hp), elem, link),	\
   			     (ep1), (epN), link)
   
  +/**
  + * Splice the sequence ep1..epN into the ring after the last element
  + *   (..hp.. becomes ..ep1..epN..hp..)
  + * @param hp   Head of the ring
  + * @param ep1  First element in the sequence to splice in
  + * @param epN  Last element in the sequence to splice in
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_SPLICE_TAIL(head *hp, elem *ep1, elem *epN, struct elem, APR_RING_ENTRY
link)
  + */
   #define APR_RING_SPLICE_TAIL(hp, ep1, epN, elem, link)			\
   	APR_RING_SPLICE_BEFORE(APR_RING_SENTINEL((hp), elem, link),	\
   			     (ep1), (epN), link)
   
  +/**
  + * Insert the element nep into the ring before the first element
  + *   (..hp.. becomes ..hp..nep..)
  + * @param hp   Head of the ring
  + * @param nep  Element to insert
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_INSERT_HEAD(head *hp, elem *nep, struct elem, APR_RING_ENTRY
link)
  + */
   #define APR_RING_INSERT_HEAD(hp, nep, elem, link)			\
   	APR_RING_SPLICE_HEAD((hp), (nep), (nep), elem, link)
   
  +/**
  + * Insert the element nep into the ring after the last element
  + *   (..hp.. becomes ..nep..hp..)
  + * @param hp   Head of the ring
  + * @param nep  Element to insert
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_INSERT_TAIL(head *hp, elem *nep, struct elem, APR_RING_ENTRY
link)
  + */
   #define APR_RING_INSERT_TAIL(hp, nep, elem, link)			\
   	APR_RING_SPLICE_TAIL((hp), (nep), (nep), elem, link)
   
  -/*
  - * Concatenating ring h2 onto the end of ring h1 leaves h2 empty.
  +/**
  + * Concatenate ring h2 onto the end of ring h1, leaving h2 empty.
  + * @param h1   Head of the ring to concatenate onto
  + * @param h2   Head of the ring to concatenate
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_CONCAT(head *h1, head *h2, struct elem, APR_RING_ENTRY link)
    */
  -#define APR_RING_CONCAT(h1, h2, elem, link) do {				\
  -	if (!APR_RING_EMPTY((h2), elem, link)) {				\
  +#define APR_RING_CONCAT(h1, h2, elem, link) 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);		\
  @@ -206,33 +339,106 @@
   	}								\
       } while (0)
   
  -/*
  - * Removing elements. Be warned that the unspliced elements are left
  - * with dangling pointers at either end!
  +
  +/**
  + * Unsplice a sequence of elements from a ring
  + * @warning The unspliced sequence is left with dangling pointers at either end
  + * @param ep1  First element in the sequence to unsplice
  + * @param epN  Last element in the sequence to unsplice
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_UNSPLICE(elem *ep1, elem *epN, APR_RING_ENTRY link)
    */
   #define APR_RING_UNSPLICE(ep1, epN, link) 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);				\
  +	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)
   
  +/**
  + * Remove a single element from a ring
  + * @warning The unspliced element is left with dangling pointers at either end
  + * @param ep   Element to remove
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @deffunc void APR_RING_REMOVE(elem *ep, APR_RING_ENTRY link)
  + */
   #define APR_RING_REMOVE(ep, link)					\
       APR_RING_UNSPLICE((ep), (ep), link)
   
  -/*
  - * Iteration.
  +
  +/**
  + * Iterate through a ring
  + * @param ep The current element
  + * @param hp The ring to iterate over
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @tip This is the same as either:
  + * <pre>
  + *	ep = APR_RING_FIRST(hp);
  + * 	while (ep != APR_RING_SENTINEL(hp, elem, link)) {
  + *	    ...
  + * 	    ep = APR_RING_NEXT(ep, link);
  + * 	}
  + *   OR
  + * 	for (ep = APR_RING_FIRST(hp);
  + *           ep != APR_RING_SENTINEL(hp, elem, link);
  + *           ep = APR_RING_NEXT(ep, link)) {
  + *	    ...
  + * 	}
  + * </pre>
  + * @deffunc void APR_RING_FOREACH(elem *ep, head *hp, struct elem, APR_RING_ENTRY link)
    */
   #define APR_RING_FOREACH(ep, hp, elem, link)				\
       for ((ep)  = APR_RING_FIRST((hp));					\
   	 (ep) != APR_RING_SENTINEL((hp), elem, link);			\
   	 (ep)  = APR_RING_NEXT((ep), link))
   
  +/**
  + * Iterate through a ring backwards
  + * @param ep The current element
  + * @param hp The ring to iterate over
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @see APR_RING_FOREACH
  + * @deffunc void APR_RING_FOREACH_REVERSE(elem *ep, head *hp, struct elem, APR_RING_ENTRY
link)
  + */
   #define APR_RING_FOREACH_REVERSE(ep, hp, elem, link)			\
       for ((ep)  = APR_RING_LAST((hp));					\
   	 (ep) != APR_RING_SENTINEL((hp), elem, link);			\
   	 (ep)  = APR_RING_PREV((ep), link))
   
  +
  +/* Debugging tools: */
  +
  +/**
  + * Print a single pointer value to STDERR
  + *   (This is a no-op unless APR_RING_DEBUG is defined.)
  + * @param msg Descriptive message
  + * @param ptr Pointer value to print
  + * @deffunc void APR_RING_CHECK_ONE(char *msg, void *ptr)
  + */
  +/**
  + * 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.)
  + * @param hp   Head of the ring
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @param msg  Descriptive message
  + * @deffunc void APR_RING_CHECK(head *hp, struct elem, APR_RING_ENTRY link, char *msg)
  + */
  +/**
  + * 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.)
  + * @param ep   The element
  + * @param elem The name of the element struct
  + * @param link The name of the APR_RING_ENTRY in the element struct
  + * @param msg  Descriptive message
  + * @deffunc void APR_RING_CHECK_ELEM(elem *ep, struct elem, APR_RING_ENTRY link, char *msg)
  + */
   #ifdef APR_RING_DEBUG
   #include <stdio.h>
   #define APR_RING_CHECK_ONE(msg, ptr)					\
  @@ -253,11 +459,11 @@
   		    APR_RING_PREV(APR_RING_NEXT(this, link), link));	\
   	    fprintf(stderr, "\telem->prev->next %p\n",			\
   		    APR_RING_NEXT(APR_RING_PREV(this, link), link));	\
  -	    if (APR_RING_PREV(APR_RING_NEXT(this, link), link) != this) {	\
  +	    if (APR_RING_PREV(APR_RING_NEXT(this, link), link) != this) { \
   		fprintf(stderr, "\t*** this->next->prev != this\n");	\
   		break;							\
   	    }								\
  -	    if (APR_RING_NEXT(APR_RING_PREV(this, link), link) != this) {	\
  +	    if (APR_RING_NEXT(APR_RING_PREV(this, link), link) != this) { \
   		fprintf(stderr, "\t*** this->prev->next != this\n");	\
   		break;							\
   	    }								\
  
  
  

Mime
View raw message