December 13th Tuesday (十二月 十三日 木曜日)

Buckets and Brigades

  Buckets and brigades is a kind of stream representation in Apache.  It can be passed through a layered I/O system
without unnecessary copying.  It forms the basis of Apache's data handling, I/O, and filter chain.

  A Bucket brigade is a doublely linke list (ring) of buckets.  Buckets are passed around only as members of a brigade,
although singleton buckets can occur for short periods of time.

  Buckets are data stores of various types. They can refer to data in memory, or part of a file or mmap area, or the output
of a process, among other things.

  The following bucket types are supported natively in APR:

* File--bucket contents are a file. Commonly used when serving a static file.
* Pipe--bucket contents are a pipe (filesystem FIFO).
* Socket--bucket contents are a socket. Most commonly used by the network filters. stdio-like buffered I/O.
* Heap--bucket contents are heap memory. Used for
* Mmap--bucket contents are an mmapped file.
* Immortal--bucket contents are memory, which is guaranteed to be valid for at least the lifetime of the bucket.
* Pool--bucket contents are allocated on a pool.
* Transient--bucket contents may go out of scope and disappear.
* Flush(metadata)--the brigade’s contents should be flushed before continuing. In Apache, that means passing whatever data
is available to the next filter in the chain.
* EOS (metadata)--end of data.The following bucket types are supported natively in APR:
* File--bucket contents are a file. Commonly used when serving a static file.
* Pipe--bucket contents are a pipe (filesystem FIFO).
* Socket--bucket contents are a socket. Most commonly used by the network filters. stdio-like buffered I/O.
* Heap--bucket contents are heap memory. Used for
* Mmap--bucket contents are an mmapped file.
* Immortal--bucket contents are memory, which is guaranteed to be valid for at least the lifetime of the bucket.
* Pool--bucket contents are allocated on a pool.
* Transient--bucket contents may go out of scope and disappear.
* Flush(metadata)--the brigade’s contents should be flushed before continuing.  In Apache, that means passing whatever data
is available to the next filter in the chain.
* EOS (metadata)--end of data.

  Other types may also be implemented--indeed, additional metadata types are used internally in Apache.  This author has implemented
bucket types for SQL queries (using apr_dbd) and for script fragments; both of these types execute and convert data to another bucket
type when read.

  Buckets also have some type-dependent accessor functions:

  Thereadfunction returns the address and size of the data in the bucket. If the data isn’t in memory, then it is read in and the bucket
changes type so that it can refer to the new location of the data. If all of the data cannot fit in the bucket, then a new bucket is inserted
into the brigade to hold the rest of it.

  The split function divides the data in a bucket into two regions. After a split, the original bucket refers to the first part of the data
and a new bucket inserted into the brigade after the original bucket refers to the second part of the data.  Reference counts are maintained
as necessary.

  Thesetasidefunction ensures that the data in the bucket has an adequate lifetime. For example, sometimes it is convenient to create a bucket
referring to data on the stack in the expectation that it will be consumed (e.g., output to the network) before the stack is unwound. If that
expectation turns out not to be valid, the setaside function is called to move the data somewhere safer.

  Thecopyfunction makes a duplicate of the bucket structure as long as it’s possible to have multiple references to a single copy of the data
itself.  Not all bucket types can be copied.

  The destroy function maintains the reference counts on the resources used by a bucket and frees them if necessary.