You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by jw...@apache.org on 2001/08/10 01:55:27 UTC
cvs commit: apr-util/include apr_buckets.h apr_ring.h
jwoolley 01/08/09 16:55:27
Modified: include apr_buckets.h apr_ring.h
Log:
Misunderstandings about APR_BRIGADE_FOREACH() must be just about one of
the most common problems people stumble on when they try to use the
buckets API. This adds a big honkin warning to the documentation for
APR_BRIGADE_FOREACH and APR_RING_FOREACH that explains the limitations
and gives an example for how to work around them.
Revision Changes Path
1.108 +16 -0 apr-util/include/apr_buckets.h
Index: apr_buckets.h
===================================================================
RCS file: /home/cvs/apr-util/include/apr_buckets.h,v
retrieving revision 1.107
retrieving revision 1.108
diff -u -d -u -r1.107 -r1.108
--- apr_buckets.h 2001/08/08 22:24:04 1.107
+++ apr_buckets.h 2001/08/09 23:55:27 1.108
@@ -337,6 +337,22 @@
* ...
* }
* </pre>
+ * @warning Be aware that you *cannot* change the value of e within
+ * the foreach loop, nor can you destroy or otherwise modify the
+ * bucket pointed to by e. If you do, then APR_BRIGADE_FOREACH
+ * will have no way to find out what bucket to use for its next
+ * iteration. The reason for this can be seen by looking closely
+ * at the equivalent loops given in the tip above. So, for example,
+ * if you are writing a loop that empties out a brigade one bucket
+ * at a time, APR_BRIGADE_FOREACH just won't work for you. Do it
+ * by hand, like so:
+ * <pre>
+ * while (!APR_BRIGADE_EMPTY(b)) {
+ * e = APR_BRIGADE_FIRST(b);
+ * ...
+ * apr_bucket_delete(e);
+ * }
+ * </pre>
* @deffunc void APR_BRIGADE_FOREACH(apr_bucket *e, apr_bucket_brigade *b)
*/
#define APR_BRIGADE_FOREACH(e, b) \
1.9 +16 -0 apr-util/include/apr_ring.h
Index: apr_ring.h
===================================================================
RCS file: /home/cvs/apr-util/include/apr_ring.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -u -r1.8 -r1.9
--- apr_ring.h 2001/02/18 00:10:52 1.8
+++ apr_ring.h 2001/08/09 23:55:27 1.9
@@ -386,6 +386,22 @@
* ...
* }
* </pre>
+ * @warning Be aware that you *cannot* change the value of ep within
+ * the foreach loop, nor can you destroy or otherwise modify the
+ * ring element pointed to by ep. If you do, then APR_RING_FOREACH
+ * will have no way to find out what element to use for its next
+ * iteration. The reason for this can be seen by looking closely
+ * at the equivalent loops given in the tip above. So, for example,
+ * if you are writing a loop that empties out a ring one element
+ * at a time, APR_RING_FOREACH just won't work for you. Do it
+ * by hand, like so:
+ * <pre>
+ * while (!APR_RING_EMPTY(hp, elem, link)) {
+ * ep = APR_RING_FIRST(hp);
+ * ...
+ * APR_RING_REMOVE(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) \