Added: apr/site/trunk/docs/docs/apr/trunk/group___a_p_r___util___bucket___brigades.html URL: http://svn.apache.org/viewvc/apr/site/trunk/docs/docs/apr/trunk/group___a_p_r___util___bucket___brigades.html?rev=784636&view=auto ============================================================================== --- apr/site/trunk/docs/docs/apr/trunk/group___a_p_r___util___bucket___brigades.html (added) +++ apr/site/trunk/docs/docs/apr/trunk/group___a_p_r___util___bucket___brigades.html Mon Jun 15 00:01:38 2009 @@ -0,0 +1,2868 @@ + + +Apache Portable Runtime: Bucket Brigades + + + + + +
+

Bucket Brigades
+ +[APR Utility Functions] +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Data Structures

struct  apr_bucket_type_t
struct  apr_bucket
struct  apr_bucket_brigade
struct  apr_bucket_refcount
struct  apr_bucket_heap
struct  apr_bucket_pool
struct  apr_bucket_mmap
struct  apr_bucket_file
union  apr_bucket_structs

Defines

#define APR_BUCKET_BUFF_SIZE   8000
#define APR_BRIGADE_CHECK_CONSISTENCY(b)
#define APR_BUCKET_CHECK_CONSISTENCY(e)
#define APR_BRIGADE_SENTINEL(b)   APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
#define APR_BRIGADE_EMPTY(b)   APR_RING_EMPTY(&(b)->list, apr_bucket, link)
#define APR_BRIGADE_FIRST(b)   APR_RING_FIRST(&(b)->list)
#define APR_BRIGADE_LAST(b)   APR_RING_LAST(&(b)->list)
#define APR_BRIGADE_INSERT_HEAD(b, e)
#define APR_BRIGADE_INSERT_TAIL(b, e)
#define APR_BRIGADE_CONCAT(a, b)
#define APR_BRIGADE_PREPEND(a, b)
#define APR_BUCKET_INSERT_BEFORE(a, b)
#define APR_BUCKET_INSERT_AFTER(a, b)
#define APR_BUCKET_NEXT(e)   APR_RING_NEXT((e), link)
#define APR_BUCKET_PREV(e)   APR_RING_PREV((e), link)
#define APR_BUCKET_REMOVE(e)   APR_RING_REMOVE((e), link)
#define APR_BUCKET_INIT(e)   APR_RING_ELEM_INIT((e), link)
#define APR_BUCKET_IS_METADATA(e)   ((e)->type->is_metadata)
#define APR_BUCKET_IS_FLUSH(e)   ((e)->type == &apr_bucket_type_flush)
#define APR_BUCKET_IS_EOS(e)   ((e)->type == &apr_bucket_type_eos)
#define APR_BUCKET_IS_FILE(e)   ((e)->type == &apr_bucket_type_file)
#define APR_BUCKET_IS_PIPE(e)   ((e)->type == &apr_bucket_type_pipe)
#define APR_BUCKET_IS_SOCKET(e)   ((e)->type == &apr_bucket_type_socket)
#define APR_BUCKET_IS_HEAP(e)   ((e)->type == &apr_bucket_type_heap)
#define APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)
#define APR_BUCKET_IS_IMMORTAL(e)   ((e)->type == &apr_bucket_type_immortal)
#define APR_BUCKET_IS_MMAP(e)   ((e)->type == &apr_bucket_type_mmap)
#define APR_BUCKET_IS_POOL(e)   ((e)->type == &apr_bucket_type_pool)
#define APR_BUCKET_ALLOC_SIZE   APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
#define apr_bucket_destroy(e)
#define apr_bucket_delete(e)
#define apr_bucket_read(e, str, len, block)   (e)->type->read(e, str, len, block)
#define apr_bucket_setaside(e, p)   (e)->type->setaside(e,p)
#define apr_bucket_split(e, point)   (e)->type->split(e, point)
#define apr_bucket_copy(e, c)   (e)->type->copy(e, c)

Typedefs

typedef struct apr_bucket_brigade apr_bucket_brigade
typedef struct apr_bucket apr_bucket
typedef struct apr_bucket_alloc_t apr_bucket_alloc_t
typedef struct apr_bucket_type_t apr_bucket_type_t
typedef apr_status_t(* apr_brigade_flush )(apr_bucket_brigade *bb, void *ctx)
typedef struct apr_bucket_refcount apr_bucket_refcount
typedef struct apr_bucket_heap apr_bucket_heap
typedef struct apr_bucket_pool apr_bucket_pool
typedef struct apr_bucket_mmap apr_bucket_mmap
typedef struct apr_bucket_file apr_bucket_file
typedef union apr_bucket_structs apr_bucket_structs

Enumerations

enum  apr_read_type_e { APR_BLOCK_READ, +APR_NONBLOCK_READ + }

Functions

 APU_DECLARE (apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p
 APU_DECLARE (apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b)
 APU_DECLARE_NONSTD (apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b
 APU_DECLARE (apr_bucket *) apr_brigade_insert_file(apr_bucket_brigade *bb
 APU_DECLARE_NONSTD (apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p)
 APU_DECLARE_NONSTD (void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list)
 APU_DECLARE_NONSTD (void *) apr_bucket_alloc(apr_size_t size
+const char apr_size_t void(*) free_func (void *data))

Variables

+apr_bucket_alloc_tlist
+apr_buckete
+apr_bucket apr_bucket_brigadea
+apr_off_t point
+apr_off_t apr_bucket ** after_point
+int read_all
+int apr_off_t * length
+char * c
+char apr_size_t * len
+char apr_size_t apr_pool_tpool
+apr_bucket_brigadebbIn
+apr_bucket_brigade apr_read_type_e block
+apr_bucket_brigade
+apr_read_type_e apr_off_t 
maxbytes
+struct iovec * vec
+struct iovec int * nvec
+apr_brigade_flush flush
+apr_brigade_flush void * ctx
+apr_brigade_flush void va_list va
+apr_brigade_flush void const char * str
+apr_brigade_flush void const
+char apr_size_t 
nbyte
+apr_brigade_flush void
+apr_brigade_flush void const
+char * 
fmt
+apr_file_tf
+apr_file_t apr_off_t start
+apr_file_t apr_off_t apr_off_t
+apr_pool_t
p
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_flush
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_eos
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_file
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_heap
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_mmap
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_pool
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_pipe
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_immortal
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_transient
APU_DECLARE_DATA const
+apr_bucket_type_t 
apr_bucket_type_socket
+apr_bucket ** b
+void * data
+const char * buf
+apr_size_t void(* free_func )(void *data)
+apr_mmap_tmm
+apr_socket_tthissock
+apr_file_tthispipe
+apr_off_t offset
+apr_file_tfd
+int enabled
+

Define Documentation

+ +
+
+ + + + + + + + + +
#define APR_BRIGADE_CHECK_CONSISTENCY (  ) 
+
+
+ +

+checks the ring pointers in a bucket brigade for consistency. an abort() will be triggered if any inconsistencies are found. note: this is a no-op unless APR_BUCKET_DEBUG is defined.

Parameters:
+ + +
b The brigade
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BRIGADE_CONCAT (a,
 ) 
+
+
+ +

+Value:

do {                                    \
+        APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);      \
+        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
+    } while (0)
+
Concatenate brigade b onto the end of brigade a, leaving brigade b empty
Parameters:
+ + + +
a The first brigade
b The second brigade
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BRIGADE_EMPTY (  )    APR_RING_EMPTY(&(b)->list, apr_bucket, link)
+
+
+ +

+Determine if the bucket brigade is empty

Parameters:
+ + +
b The brigade to check
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BRIGADE_FIRST (  )    APR_RING_FIRST(&(b)->list)
+
+
+ +

+Return the first bucket in a brigade

Parameters:
+ + +
b The brigade to query
+
+
Returns:
The first bucket in the brigade
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BRIGADE_INSERT_HEAD (b,
 ) 
+
+
+ +

+Value:

do {                            \
+        apr_bucket *ap__b = (e);                                        \
+        APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);      \
+        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
+    } while (0)
+
Insert a list of buckets at the front of a brigade
Parameters:
+ + + +
b The brigade to add to
e The first bucket in a list of buckets to insert
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BRIGADE_INSERT_TAIL (b,
 ) 
+
+
+ +

+Value:

do {                            \
+        apr_bucket *ap__b = (e);                                        \
+        APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);      \
+        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
+    } while (0)
+
Insert a list of buckets at the end of a brigade
Parameters:
+ + + +
b The brigade to add to
e The first bucket in a list of buckets to insert
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BRIGADE_LAST (  )    APR_RING_LAST(&(b)->list)
+
+
+ +

+Return the last bucket in a brigade

Parameters:
+ + +
b The brigade to query
+
+
Returns:
The last bucket in the brigade
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BRIGADE_PREPEND (a,
 ) 
+
+
+ +

+Value:

do {                                    \
+        APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);     \
+        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
+    } while (0)
+
Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
Parameters:
+ + + +
a The first brigade
b The second brigade
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BRIGADE_SENTINEL (  )    APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
+
+
+ +

+Wrappers around the RING macros to reduce the verbosity of the code that handles bucket brigades. The magic pointer value that indicates the head of the brigade

Remarks:
This is used to find the beginning and end of the brigade, eg:
+      while (e != APR_BRIGADE_SENTINEL(b)) {
+          ...
+          e = APR_BUCKET_NEXT(e);
+      }
+ 
+
Parameters:
+ + +
b The brigade
+
+
Returns:
The magic pointer value
+ +
+

+ +

+
+ + + + +
#define APR_BUCKET_ALLOC_SIZE   APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
+
+
+ +

+The amount that apr_bucket_alloc() should allocate in the common case. Note: this is twice as big as apr_bucket_structs to allow breathing room for third-party bucket types. +

+

+ +

+
+ + + + +
#define APR_BUCKET_BUFF_SIZE   8000
+
+
+ +

+default bucket buffer size - 8KB minus room for memory allocator headers +

+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_CHECK_CONSISTENCY (  ) 
+
+
+ +

+checks the brigade a bucket is in for ring consistency. an abort() will be triggered if any inconsistencies are found. note: this is a no-op unless APR_BUCKET_DEBUG is defined.

Parameters:
+ + +
e The bucket
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define apr_bucket_copy (e,
 )    (e)->type->copy(e, c)
+
+
+ +

+Copy a bucket.

Parameters:
+ + + +
e The bucket to copy
c Returns a pointer to the new bucket
+
+ +
+

+ +

+
+ + + + + + + + + +
#define apr_bucket_delete (  ) 
+
+
+ +

+Value:

do {                                    \
+        APR_BUCKET_REMOVE(e);                                           \
+        apr_bucket_destroy(e);                                          \
+    } while (0)
+
Delete a bucket by removing it from its brigade (if any) and then destroying it.
Remarks:
This mainly acts as an aid in avoiding code verbosity. It is the preferred exact equivalent to:
+      APR_BUCKET_REMOVE(e);
+      apr_bucket_destroy(e);
+ 
+
Parameters:
+ + +
e The bucket to delete
+
+ +
+

+ +

+
+ + + + + + + + + +
#define apr_bucket_destroy (  ) 
+
+
+ +

+Value:

do {                                    \
+        (e)->type->destroy((e)->data);                                  \
+        (e)->free(e);                                                   \
+    } while (0)
+
Free the resources used by a bucket. If multiple buckets refer to the same resource it is freed when the last one goes away.
See also:
apr_bucket_delete()
+
Parameters:
+ + +
e The bucket to destroy
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_INIT (  )    APR_RING_ELEM_INIT((e), link)
+
+
+ +

+Initialize a new bucket's prev/next pointers

Parameters:
+ + +
e The bucket to initialize
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BUCKET_INSERT_AFTER (a,
 ) 
+
+
+ +

+Value:

do {                            \
+        apr_bucket *ap__a = (a), *ap__b = (b);                          \
+        APR_RING_INSERT_AFTER(ap__a, ap__b, link);                      \
+        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
+    } while (0)
+
Insert a list of buckets after a specified bucket
Parameters:
+ + + +
a The bucket to insert after
b The buckets to insert
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define APR_BUCKET_INSERT_BEFORE (a,
 ) 
+
+
+ +

+Value:

do {                            \
+        apr_bucket *ap__a = (a), *ap__b = (b);                          \
+        APR_RING_INSERT_BEFORE(ap__a, ap__b, link);                     \
+        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
+    } while (0)
+
Insert a list of buckets before a specified bucket
Parameters:
+ + + +
a The bucket to insert before
b The buckets to insert
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_EOS (  )    ((e)->type == &apr_bucket_type_eos)
+
+
+ +

+Determine if a bucket is an EOS bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_FILE (  )    ((e)->type == &apr_bucket_type_file)
+
+
+ +

+Determine if a bucket is a FILE bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_FLUSH (  )    ((e)->type == &apr_bucket_type_flush)
+
+
+ +

+Determine if a bucket is a FLUSH bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_HEAP (  )    ((e)->type == &apr_bucket_type_heap)
+
+
+ +

+Determine if a bucket is a HEAP bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_IMMORTAL (  )    ((e)->type == &apr_bucket_type_immortal)
+
+
+ +

+Determine if a bucket is a IMMORTAL bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_METADATA (  )    ((e)->type->is_metadata)
+
+
+ +

+Determine if a bucket contains metadata. An empty bucket is safe to arbitrarily remove if and only if this is false.

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_MMAP (  )    ((e)->type == &apr_bucket_type_mmap)
+
+
+ +

+Determine if a bucket is a MMAP bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_PIPE (  )    ((e)->type == &apr_bucket_type_pipe)
+
+
+ +

+Determine if a bucket is a PIPE bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_POOL (  )    ((e)->type == &apr_bucket_type_pool)
+
+
+ +

+Determine if a bucket is a POOL bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_SOCKET (  )    ((e)->type == &apr_bucket_type_socket)
+
+
+ +

+Determine if a bucket is a SOCKET bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_IS_TRANSIENT (  )    ((e)->type == &apr_bucket_type_transient)
+
+
+ +

+Determine if a bucket is a TRANSIENT bucket

Parameters:
+ + +
e The bucket to inspect
+
+
Returns:
true or false
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_NEXT (  )    APR_RING_NEXT((e), link)
+
+
+ +

+Get the next bucket in the list

Parameters:
+ + +
e The current bucket
+
+
Returns:
The next bucket
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_PREV (  )    APR_RING_PREV((e), link)
+
+
+ +

+Get the previous bucket in the list

Parameters:
+ + +
e The current bucket
+
+
Returns:
The previous bucket
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
#define apr_bucket_read (e,
str,
len,
block   )    (e)->type->read(e, str, len, block)
+
+
+ +

+Read some data from the bucket.

+The apr_bucket_read function returns a convenient amount of data from the bucket provided, writing the address and length of the data to the pointers provided by the caller. The function tries as hard as possible to avoid a memory copy.

+Buckets are expected to be a member of a brigade at the time they are read.

+In typical application code, buckets are read in a loop, and after each bucket is read and processed, it is moved or deleted from the brigade and the next bucket read.

+The definition of "convenient" depends on the type of bucket that is being read, and is decided by APR. In the case of memory based buckets such as heap and immortal buckets, a pointer will be returned to the location of the buffer containing the complete contents of the bucket.

+Some buckets, such as the socket bucket, might have no concept of length. If an attempt is made to read such a bucket, the apr_bucket_read function will read a convenient amount of data from the socket. The socket bucket is magically morphed into a heap bucket containing the just-read data, and a new socket bucket is inserted just after this heap bucket.

+To understand why apr_bucket_read might do this, consider the loop described above to read and process buckets. The current bucket is magically morphed into a heap bucket and returned to the caller. The caller processes the data, and deletes the heap bucket, moving onto the next bucket, the new socket bucket. This process repeats, giving the illusion of a bucket brigade that contains potentially infinite amounts of data. It is up to the caller to decide at what point to stop reading buckets.

+Some buckets, such as the file bucket, might have a fixed size, but be significantly larger than is practical to store in RAM in one go. As with the socket bucket, if an attempt is made to read from a file bucket, the file bucket is magically morphed into a heap bucket containing a convenient amount of data read from the current offset in the file. During the read, the offset will be moved forward on the file, and a new file bucket will be inserted directly after the current bucket representing the remainder of the file. If the heap bucket was large enough to store the whole remainder of the file, no more file buckets are inserted, and the file bucket will disappear completely.

+The pattern for reading buckets described above does create the illusion that the code is willing to swallow buckets that might be too large for the system to handle in one go. This however is just an illusion: APR will always ensure that large (file) or infinite (socket) buckets are broken into convenient bite sized heap buckets before data is returned to the caller.

+There is a potential gotcha to watch for: if buckets are read in a loop, and aren't deleted after being processed, the potentially large bucket will slowly be converted into RAM resident heap buckets. If the file is larger than available RAM, an out of memory condition could be caused if the application is not careful to manage this.

+

Parameters:
+ + + + + +
e The bucket to read from
str The location to store a pointer to the data in
len The location to store the amount of data read
block Whether the read function blocks
+
+ +
+

+ +

+
+ + + + + + + + + +
#define APR_BUCKET_REMOVE (  )    APR_RING_REMOVE((e), link)
+
+
+ +

+Remove a bucket from its bucket brigade

Parameters:
+ + +
e The bucket to remove
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define apr_bucket_setaside (e,
 )    (e)->type->setaside(e,p)
+
+
+ +

+Setaside data so that stack data is not destroyed on returning from the function

Parameters:
+ + + +
e The bucket to setaside
p The pool to setaside into
+
+ +
+

+ +

+
+ + + + + + + + + + + + +
#define apr_bucket_split (e,
point   )    (e)->type->split(e, point)
+
+
+ +

+Split one bucket in two at the point provided.

+Once split, the original bucket becomes the first of the two new buckets.

+(It is assumed that the bucket is a member of a brigade when this function is called).

Parameters:
+ + + +
e The bucket to split
point The offset to split the bucket at
+
+ +
+

+


Typedef Documentation

+ +
+
+ + + + +
typedef apr_status_t(* apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx)
+
+
+ +

+Function called when a brigade should be flushed +

+

+ +

+
+ + + + +
typedef struct apr_bucket apr_bucket
+
+
+ +

+

See also:
apr_bucket
+ +
+

+ +

+
+ + + + +
typedef struct apr_bucket_alloc_t apr_bucket_alloc_t
+
+
+ +

+

See also:
apr_bucket_alloc_t
+ +
+

+ +

+
+ + [... 1535 lines stripped ...]