home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277195_apr_buckets.h < prev    next >
C/C++ Source or Header  |  2004-02-13  |  60KB  |  1,495 lines
  1. /* Copyright 2000-2004 The Apache Software Foundation
  2.  *
  3.  * Licensed under the Apache License, Version 2.0 (the "License");
  4.  * you may not use this file except in compliance with the License.
  5.  * You may obtain a copy of the License at
  6.  *
  7.  *     http://www.apache.org/licenses/LICENSE-2.0
  8.  *
  9.  * Unless required by applicable law or agreed to in writing, software
  10.  * distributed under the License is distributed on an "AS IS" BASIS,
  11.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12.  * See the License for the specific language governing permissions and
  13.  * limitations under the License.
  14.  */
  15. /**
  16.  * @file apr_buckets.h
  17.  * @brief APR-UTIL Buckets/Bucket Brigades
  18.  */
  19.  
  20. #ifndef APR_BUCKETS_H
  21. #define APR_BUCKETS_H
  22.  
  23. #if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG)
  24. #define APR_RING_DEBUG
  25. #endif
  26.  
  27. #include "apu.h"
  28. #include "apr_network_io.h"
  29. #include "apr_file_io.h"
  30. #include "apr_general.h"
  31. #include "apr_mmap.h"
  32. #include "apr_errno.h"
  33. #include "apr_ring.h"
  34. #include "apr.h"
  35. #if APR_HAVE_SYS_UIO_H
  36. #include <sys/uio.h>    /* for struct iovec */
  37. #endif
  38. #if APR_HAVE_STDARG_H
  39. #include <stdarg.h>
  40. #endif
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. /**
  47.  * @defgroup APR_Util_Bucket_Brigades Bucket Brigades
  48.  * @ingroup APR_Util
  49.  * @{ 
  50.  */
  51.  
  52. /** default bucket buffer size - 8KB minus room for memory allocator headers */
  53. #define APR_BUCKET_BUFF_SIZE 8000
  54.  
  55. /** Determines how a bucket or brigade should be read */
  56. typedef enum {
  57.     APR_BLOCK_READ,   /**< block until data becomes available */
  58.     APR_NONBLOCK_READ /**< return immediately if no data is available */
  59. } apr_read_type_e;
  60.  
  61. /**
  62.  * The one-sentence buzzword-laden overview: Bucket brigades represent
  63.  * a complex data stream that can be passed through a layered IO
  64.  * system without unnecessary copying. A longer overview follows...
  65.  *
  66.  * A bucket brigade is a doubly linked list (ring) of buckets, so we
  67.  * aren't limited to inserting at the front and removing at the end.
  68.  * Buckets are only passed around as members of a brigade, although
  69.  * singleton buckets can occur for short periods of time.
  70.  *
  71.  * Buckets are data stores of various types. They can refer to data in
  72.  * memory, or part of a file or mmap area, or the output of a process,
  73.  * etc. Buckets also have some type-dependent accessor functions:
  74.  * read, split, copy, setaside, and destroy.
  75.  *
  76.  * read returns the address and size of the data in the bucket. If the
  77.  * data isn't in memory then it is read in and the bucket changes type
  78.  * so that it can refer to the new location of the data. If all the
  79.  * data doesn't fit in the bucket then a new bucket is inserted into
  80.  * the brigade to hold the rest of it.
  81.  *
  82.  * split divides the data in a bucket into two regions. After a split
  83.  * the original bucket refers to the first part of the data and a new
  84.  * bucket inserted into the brigade after the original bucket refers
  85.  * to the second part of the data. Reference counts are maintained as
  86.  * necessary.
  87.  *
  88.  * setaside ensures that the data in the bucket has a long enough
  89.  * lifetime. Sometimes it is convenient to create a bucket referring
  90.  * to data on the stack in the expectation that it will be consumed
  91.  * (output to the network) before the stack is unwound. If that
  92.  * expectation turns out not to be valid, the setaside function is
  93.  * called to move the data somewhere safer.
  94.  *
  95.  * copy makes a duplicate of the bucket structure as long as it's
  96.  * possible to have multiple references to a single copy of the
  97.  * data itself.  Not all bucket types can be copied.
  98.  *
  99.  * destroy maintains the reference counts on the resources used by a
  100.  * bucket and frees them if necessary.
  101.  *
  102.  * Note: all of the above functions have wrapper macros (apr_bucket_read(),
  103.  * apr_bucket_destroy(), etc), and those macros should be used rather
  104.  * than using the function pointers directly.
  105.  *
  106.  * To write a bucket brigade, they are first made into an iovec, so that we
  107.  * don't write too little data at one time.  Currently we ignore compacting the
  108.  * buckets into as few buckets as possible, but if we really want good
  109.  * performance, then we need to compact the buckets before we convert to an
  110.  * iovec, or possibly while we are converting to an iovec.
  111.  */
  112.  
  113. /*
  114.  * Forward declaration of the main types.
  115.  */
  116.  
  117. /** @see apr_bucket_brigade */
  118. typedef struct apr_bucket_brigade apr_bucket_brigade;
  119. /** @see apr_bucket */
  120. typedef struct apr_bucket apr_bucket;
  121. /** @see apr_bucket_alloc_t */
  122. typedef struct apr_bucket_alloc_t apr_bucket_alloc_t;
  123.  
  124. /** @see apr_bucket_type_t */
  125. typedef struct apr_bucket_type_t apr_bucket_type_t;
  126.  
  127. /**
  128.  * Basic bucket type
  129.  */
  130. struct apr_bucket_type_t {
  131.     /**
  132.      * The name of the bucket type
  133.      */
  134.     const char *name;
  135.     /** 
  136.      * The number of functions this bucket understands.  Can not be less than
  137.      * five.
  138.      */
  139.     int num_func;
  140.     /**
  141.      * Whether the bucket contains metadata (ie, information that
  142.      * describes the regular contents of the brigade).  The metadata
  143.      * is not returned by apr_bucket_read() and is not indicated by
  144.      * the ->length of the apr_bucket itself.  In other words, an
  145.      * empty bucket is safe to arbitrarily remove if and only if it
  146.      * contains no metadata.  In this sense, "data" is just raw bytes
  147.      * that are the "content" of the brigade and "metadata" describes
  148.      * that data but is not a proper part of it.
  149.      */
  150.     enum {
  151.         /** This bucket type represents actual data to send to the client. */
  152.         APR_BUCKET_DATA = 0,
  153.         /** This bucket type represents metadata. */
  154.         APR_BUCKET_METADATA = 1
  155.     } is_metadata;
  156.     /**
  157.      * Free the private data and any resources used by the bucket (if they
  158.      *  aren't shared with another bucket).  This function is required to be
  159.      *  implemented for all bucket types, though it might be a no-op on some
  160.      *  of them (namely ones that never allocate any private data structures).
  161.      * @param data The private data pointer from the bucket to be destroyed
  162.      */
  163.     void (*destroy)(void *data);
  164.  
  165.     /**
  166.      * Read the data from the bucket. This is required to be implemented
  167.      *  for all bucket types.
  168.      * @param b The bucket to read from
  169.      * @param str A place to store the data read.  Allocation should only be
  170.      *            done if absolutely necessary. 
  171.      * @param len The amount of data read.
  172.      * @param block Should this read function block if there is more data that
  173.      *              cannot be read immediately.
  174.      */
  175.     apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 
  176.                          apr_read_type_e block);
  177.     
  178.     /**
  179.      * Make it possible to set aside the data for at least as long as the
  180.      *  given pool. Buckets containing data that could potentially die before
  181.      *  this pool (e.g. the data resides on the stack, in a child pool of
  182.      *  the given pool, or in a disjoint pool) must somehow copy, shift, or
  183.      *  transform the data to have the proper lifetime.
  184.      * @param e The bucket to convert
  185.      * @remark Some bucket types contain data that will always outlive the
  186.      *         bucket itself. For example no data (EOS and FLUSH), or the data
  187.      *         resides in global, constant memory (IMMORTAL), or the data is on
  188.      *      the heap (HEAP). For these buckets, apr_bucket_setaside_noop can
  189.      *      be used.
  190.      */
  191.     apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool);
  192.  
  193.     /**
  194.      * Split one bucket in two at the specified position by duplicating
  195.      *  the bucket structure (not the data) and modifying any necessary
  196.      *  start/end/offset information.  If it's not possible to do this
  197.      *  for the bucket type (perhaps the length of the data is indeterminate,
  198.      *  as with pipe and socket buckets), then APR_ENOTIMPL is returned.
  199.      * @param e The bucket to split
  200.      * @param point The offset of the first byte in the new bucket
  201.      */
  202.     apr_status_t (*split)(apr_bucket *e, apr_size_t point);
  203.  
  204.     /**
  205.      * Copy the bucket structure (not the data), assuming that this is
  206.      *  possible for the bucket type. If it's not, APR_ENOTIMPL is returned.
  207.      * @param e The bucket to copy
  208.      * @param c Returns a pointer to the new bucket
  209.      */
  210.     apr_status_t (*copy)(apr_bucket *e, apr_bucket **c);
  211.  
  212. };
  213.  
  214. /**
  215.  * apr_bucket structures are allocated on the malloc() heap and
  216.  * their lifetime is controlled by the parent apr_bucket_brigade
  217.  * structure. Buckets can move from one brigade to another e.g. by
  218.  * calling APR_BRIGADE_CONCAT(). In general the data in a bucket has
  219.  * the same lifetime as the bucket and is freed when the bucket is
  220.  * destroyed; if the data is shared by more than one bucket (e.g.
  221.  * after a split) the data is freed when the last bucket goes away.
  222.  */
  223. struct apr_bucket {
  224.     /** Links to the rest of the brigade */
  225.     APR_RING_ENTRY(apr_bucket) link;
  226.     /** The type of bucket.  */
  227.     const apr_bucket_type_t *type;
  228.     /** The length of the data in the bucket.  This could have been implemented
  229.      *  with a function, but this is an optimization, because the most
  230.      *  common thing to do will be to get the length.  If the length is unknown,
  231.      *  the value of this field will be (apr_size_t)(-1).
  232.      */
  233.     apr_size_t length;
  234.     /** The start of the data in the bucket relative to the private base
  235.      *  pointer.  The vast majority of bucket types allow a fixed block of
  236.      *  data to be referenced by multiple buckets, each bucket pointing to
  237.      *  a different segment of the data.  That segment starts at base+start
  238.      *  and ends at base+start+length.  
  239.      *  If the length == (apr_size_t)(-1), then start == -1.
  240.      */
  241.     apr_off_t start;
  242.     /** type-dependent data hangs off this pointer */
  243.     void *data;    
  244.     /**
  245.      * Pointer to function used to free the bucket. This function should
  246.      * always be defined and it should be consistent with the memory
  247.      * function used to allocate the bucket. For example, if malloc() is 
  248.      * used to allocate the bucket, this pointer should point to free().
  249.      * @param e Pointer to the bucket being freed
  250.      */
  251.     void (*free)(void *e);
  252.     /** The freelist from which this bucket was allocated */
  253.     apr_bucket_alloc_t *list;
  254. };
  255.  
  256. /** A list of buckets */
  257. struct apr_bucket_brigade {
  258.     /** The pool to associate the brigade with.  The data is not allocated out
  259.      *  of the pool, but a cleanup is registered with this pool.  If the 
  260.      *  brigade is destroyed by some mechanism other than pool destruction,
  261.      *  the destroying function is responsible for killing the cleanup.
  262.      */
  263.     apr_pool_t *p;
  264.     /** The buckets in the brigade are on this list. */
  265.     /*
  266.      * The apr_bucket_list structure doesn't actually need a name tag
  267.      * because it has no existence independent of struct apr_bucket_brigade;
  268.      * the ring macros are designed so that you can leave the name tag
  269.      * argument empty in this situation but apparently the Windows compiler
  270.      * doesn't like that.
  271.      */
  272.     APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
  273.     /** The freelist from which this bucket was allocated */
  274.     apr_bucket_alloc_t *bucket_alloc;
  275. };
  276.  
  277.  
  278. /**
  279.  * Function called when a brigade should be flushed
  280.  */
  281. typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx);
  282.  
  283. /*
  284.  * define APR_BUCKET_DEBUG if you want your brigades to be checked for
  285.  * validity at every possible instant.  this will slow your code down
  286.  * substantially but is a very useful debugging tool.
  287.  */
  288. #ifdef APR_BUCKET_DEBUG
  289.  
  290. #define APR_BRIGADE_CHECK_CONSISTENCY(b)                \
  291.         APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link)
  292.  
  293. #define APR_BUCKET_CHECK_CONSISTENCY(e)                    \
  294.         APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link)
  295.  
  296. #else
  297. /**
  298.  * checks the ring pointers in a bucket brigade for consistency.  an
  299.  * abort() will be triggered if any inconsistencies are found.
  300.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  301.  * @param b The brigade
  302.  */
  303. #define APR_BRIGADE_CHECK_CONSISTENCY(b)
  304. /**
  305.  * checks the brigade a bucket is in for ring consistency.  an
  306.  * abort() will be triggered if any inconsistencies are found.
  307.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  308.  * @param e The bucket
  309.  */
  310. #define APR_BUCKET_CHECK_CONSISTENCY(e)
  311. #endif
  312.  
  313.  
  314. /**
  315.  * Wrappers around the RING macros to reduce the verbosity of the code
  316.  * that handles bucket brigades.
  317.  */
  318. /**
  319.  * The magic pointer value that indicates the head of the brigade
  320.  * @remark This is used to find the beginning and end of the brigade, eg:
  321.  * <pre>
  322.  *      while (e != APR_BRIGADE_SENTINEL(b)) {
  323.  *          ...
  324.  *          e = APR_BUCKET_NEXT(e);
  325.  *      }
  326.  * </pre>
  327.  * @param  b The brigade
  328.  * @return The magic pointer value
  329.  */
  330. #define APR_BRIGADE_SENTINEL(b)    APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
  331.  
  332. /**
  333.  * Determine if the bucket brigade is empty
  334.  * @param b The brigade to check
  335.  * @return true or false
  336.  */
  337. #define APR_BRIGADE_EMPTY(b)    APR_RING_EMPTY(&(b)->list, apr_bucket, link)
  338.  
  339. /**
  340.  * Return the first bucket in a brigade
  341.  * @param b The brigade to query
  342.  * @return The first bucket in the brigade
  343.  */
  344. #define APR_BRIGADE_FIRST(b)    APR_RING_FIRST(&(b)->list)
  345. /**
  346.  * Return the last bucket in a brigade
  347.  * @param b The brigade to query
  348.  * @return The last bucket in the brigade
  349.  */
  350. #define APR_BRIGADE_LAST(b)    APR_RING_LAST(&(b)->list)
  351.  
  352. /**
  353.  * Iterate through a bucket brigade
  354.  * @param e The current bucket
  355.  * @param b The brigade to iterate over
  356.  * @remark This is the same as either:
  357.  * <pre>
  358.  *    e = APR_BRIGADE_FIRST(b);
  359.  *     while (e != APR_BRIGADE_SENTINEL(b)) {
  360.  *        ...
  361.  *         e = APR_BUCKET_NEXT(e);
  362.  *     }
  363.  *  OR
  364.  *     for (e = APR_BRIGADE_FIRST(b);
  365.  *           e != APR_BRIGADE_SENTINEL(b);
  366.  *           e = APR_BUCKET_NEXT(e)) {
  367.  *        ...
  368.  *     }
  369.  * </pre>
  370.  * @warning Be aware that you cannot change the value of e within
  371.  * the foreach loop, nor can you destroy the bucket it points to.
  372.  * Modifying the prev and next pointers of the bucket is dangerous
  373.  * but can be done if you're careful.  If you change e's value or
  374.  * destroy the bucket it points to, then APR_BRIGADE_FOREACH
  375.  * will have no way to find out what bucket to use for its next
  376.  * iteration.  The reason for this can be seen by looking closely
  377.  * at the equivalent loops given in the tip above.  So, for example,
  378.  * if you are writing a loop that empties out a brigade one bucket
  379.  * at a time, APR_BRIGADE_FOREACH just won't work for you.  Do it
  380.  * by hand, like so:
  381.  * <pre>
  382.  *      while (!APR_BRIGADE_EMPTY(b)) {
  383.  *          e = APR_BRIGADE_FIRST(b);
  384.  *          ...
  385.  *          apr_bucket_delete(e);
  386.  *      }
  387.  * </pre>
  388.  * @deprecated This macro causes more headaches than it's worth.  Use
  389.  * one of the alternatives documented here instead; the clarity gained
  390.  * in what's really going on is well worth the extra line or two of code.
  391.  * This macro will be removed at some point in the future.
  392.  */
  393. #define APR_BRIGADE_FOREACH(e, b)                    \
  394.     APR_RING_FOREACH((e), &(b)->list, apr_bucket, link)
  395.  
  396. /**
  397.  * Insert a list of buckets at the front of a brigade
  398.  * @param b The brigade to add to
  399.  * @param e The first bucket in a list of buckets to insert
  400.  */
  401. #define APR_BRIGADE_INSERT_HEAD(b, e) do {                \
  402.     apr_bucket *ap__b = (e);                                        \
  403.     APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);    \
  404.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  405.     } while (0)
  406.  
  407. /**
  408.  * Insert a list of buckets at the end of a brigade
  409.  * @param b The brigade to add to
  410.  * @param e The first bucket in a list of buckets to insert
  411.  */
  412. #define APR_BRIGADE_INSERT_TAIL(b, e) do {                \
  413.     apr_bucket *ap__b = (e);                    \
  414.     APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);    \
  415.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  416.     } while (0)
  417.  
  418. /**
  419.  * Concatenate brigade b onto the end of brigade a, leaving brigade b empty
  420.  * @param a The first brigade
  421.  * @param b The second brigade
  422.  */
  423. #define APR_BRIGADE_CONCAT(a, b) do {                    \
  424.         APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);    \
  425.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  426.     } while (0)
  427.  
  428. /**
  429.  * Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
  430.  * @param a The first brigade
  431.  * @param b The second brigade
  432.  */
  433. #define APR_BRIGADE_PREPEND(a, b) do {                    \
  434.         APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);    \
  435.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  436.     } while (0)
  437.  
  438. /**
  439.  * Insert a list of buckets before a specified bucket
  440.  * @param a The bucket to insert before
  441.  * @param b The buckets to insert
  442.  */
  443. #define APR_BUCKET_INSERT_BEFORE(a, b) do {                \
  444.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  445.     APR_RING_INSERT_BEFORE(ap__a, ap__b, link);            \
  446.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  447.     } while (0)
  448.  
  449. /**
  450.  * Insert a list of buckets after a specified bucket
  451.  * @param a The bucket to insert after
  452.  * @param b The buckets to insert
  453.  */
  454. #define APR_BUCKET_INSERT_AFTER(a, b) do {                \
  455.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  456.     APR_RING_INSERT_AFTER(ap__a, ap__b, link);            \
  457.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  458.     } while (0)
  459.  
  460. /**
  461.  * Get the next bucket in the list
  462.  * @param e The current bucket
  463.  * @return The next bucket
  464.  */
  465. #define APR_BUCKET_NEXT(e)    APR_RING_NEXT((e), link)
  466. /**
  467.  * Get the previous bucket in the list
  468.  * @param e The current bucket
  469.  * @return The previous bucket
  470.  */
  471. #define APR_BUCKET_PREV(e)    APR_RING_PREV((e), link)
  472.  
  473. /**
  474.  * Remove a bucket from its bucket brigade
  475.  * @param e The bucket to remove
  476.  */
  477. #define APR_BUCKET_REMOVE(e)    APR_RING_REMOVE((e), link)
  478.  
  479. /**
  480.  * Initialize a new bucket's prev/next pointers
  481.  * @param e The bucket to initialize
  482.  */
  483. #define APR_BUCKET_INIT(e)    APR_RING_ELEM_INIT((e), link)
  484.  
  485. /**
  486.  * Determine if a bucket contains metadata.  An empty bucket is
  487.  * safe to arbitrarily remove if and only if this is false.
  488.  * @param e The bucket to inspect
  489.  * @return true or false
  490.  */
  491. #define APR_BUCKET_IS_METADATA(e)    ((e)->type->is_metadata)
  492.  
  493. /**
  494.  * Determine if a bucket is a FLUSH bucket
  495.  * @param e The bucket to inspect
  496.  * @return true or false
  497.  */
  498. #define APR_BUCKET_IS_FLUSH(e)       ((e)->type == &apr_bucket_type_flush)
  499. /**
  500.  * Determine if a bucket is an EOS bucket
  501.  * @param e The bucket to inspect
  502.  * @return true or false
  503.  */
  504. #define APR_BUCKET_IS_EOS(e)         ((e)->type == &apr_bucket_type_eos)
  505. /**
  506.  * Determine if a bucket is a FILE bucket
  507.  * @param e The bucket to inspect
  508.  * @return true or false
  509.  */
  510. #define APR_BUCKET_IS_FILE(e)        ((e)->type == &apr_bucket_type_file)
  511. /**
  512.  * Determine if a bucket is a PIPE bucket
  513.  * @param e The bucket to inspect
  514.  * @return true or false
  515.  */
  516. #define APR_BUCKET_IS_PIPE(e)        ((e)->type == &apr_bucket_type_pipe)
  517. /**
  518.  * Determine if a bucket is a SOCKET bucket
  519.  * @param e The bucket to inspect
  520.  * @return true or false
  521.  */
  522. #define APR_BUCKET_IS_SOCKET(e)      ((e)->type == &apr_bucket_type_socket)
  523. /**
  524.  * Determine if a bucket is a HEAP bucket
  525.  * @param e The bucket to inspect
  526.  * @return true or false
  527.  */
  528. #define APR_BUCKET_IS_HEAP(e)        ((e)->type == &apr_bucket_type_heap)
  529. /**
  530.  * Determine if a bucket is a TRANSIENT bucket
  531.  * @param e The bucket to inspect
  532.  * @return true or false
  533.  */
  534. #define APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)
  535. /**
  536.  * Determine if a bucket is a IMMORTAL bucket
  537.  * @param e The bucket to inspect
  538.  * @return true or false
  539.  */
  540. #define APR_BUCKET_IS_IMMORTAL(e)    ((e)->type == &apr_bucket_type_immortal)
  541. #if APR_HAS_MMAP
  542. /**
  543.  * Determine if a bucket is a MMAP bucket
  544.  * @param e The bucket to inspect
  545.  * @return true or false
  546.  */
  547. #define APR_BUCKET_IS_MMAP(e)        ((e)->type == &apr_bucket_type_mmap)
  548. #endif
  549. /**
  550.  * Determine if a bucket is a POOL bucket
  551.  * @param e The bucket to inspect
  552.  * @return true or false
  553.  */
  554. #define APR_BUCKET_IS_POOL(e)        ((e)->type == &apr_bucket_type_pool)
  555.  
  556. /*
  557.  * General-purpose reference counting for the various bucket types.
  558.  *
  559.  * Any bucket type that keeps track of the resources it uses (i.e.
  560.  * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
  561.  * attach a reference count to the resource so that it can be freed
  562.  * when the last bucket that uses it goes away. Resource-sharing may
  563.  * occur because of bucket splits or buckets that refer to globally
  564.  * cached data. */
  565.  
  566. /** @see apr_bucket_refcount */
  567. typedef struct apr_bucket_refcount apr_bucket_refcount;
  568. /**
  569.  * The structure used to manage the shared resource must start with an
  570.  * apr_bucket_refcount which is updated by the general-purpose refcount
  571.  * code. A pointer to the bucket-type-dependent private data structure
  572.  * can be cast to a pointer to an apr_bucket_refcount and vice versa.
  573.  */
  574. struct apr_bucket_refcount {
  575.     /** The number of references to this bucket */
  576.     int          refcount;
  577. };
  578.  
  579. /*  *****  Reference-counted bucket types  *****  */
  580.  
  581. /** @see apr_bucket_heap */
  582. typedef struct apr_bucket_heap apr_bucket_heap;
  583. /**
  584.  * A bucket referring to data allocated off the heap.
  585.  */
  586. struct apr_bucket_heap {
  587.     /** Number of buckets using this memory */
  588.     apr_bucket_refcount  refcount;
  589.     /** The start of the data actually allocated.  This should never be
  590.      * modified, it is only used to free the bucket.
  591.      */
  592.     char    *base;
  593.     /** how much memory was allocated */
  594.     apr_size_t  alloc_len;
  595.     /** function to use to delete the data */
  596.     void (*free_func)(void *data);
  597. };
  598.  
  599. /** @see apr_bucket_pool */
  600. typedef struct apr_bucket_pool apr_bucket_pool;
  601. /**
  602.  * A bucket referring to data allocated from a pool
  603.  */
  604. struct apr_bucket_pool {
  605.     /** The pool bucket must be able to be easily morphed to a heap
  606.      * bucket if the pool gets cleaned up before all references are
  607.      * destroyed.  This apr_bucket_heap structure is populated automatically
  608.      * when the pool gets cleaned up, and subsequent calls to pool_read()
  609.      * will result in the apr_bucket in question being morphed into a
  610.      * regular heap bucket.  (To avoid having to do many extra refcount
  611.      * manipulations and b->data manipulations, the apr_bucket_pool
  612.      * struct actually *contains* the apr_bucket_heap struct that it
  613.      * will become as its first element; the two share their
  614.      * apr_bucket_refcount members.)
  615.      */
  616.     apr_bucket_heap  heap;
  617.     /** The block of data actually allocated from the pool.
  618.      * Segments of this block are referenced by adjusting
  619.      * the start and length of the apr_bucket accordingly.
  620.      * This will be NULL after the pool gets cleaned up.
  621.      */
  622.     const char *base;
  623.     /** The pool the data was allocated from.  When the pool
  624.      * is cleaned up, this gets set to NULL as an indicator
  625.      * to pool_read() that the data is now on the heap and
  626.      * so it should morph the bucket into a regular heap
  627.      * bucket before continuing.
  628.      */
  629.     apr_pool_t *pool;
  630.     /** The freelist this structure was allocated from, which is
  631.      * needed in the cleanup phase in order to allocate space on the heap
  632.      */
  633.     apr_bucket_alloc_t *list;
  634. };
  635.  
  636. #if APR_HAS_MMAP
  637. /** @see apr_bucket_mmap */
  638. typedef struct apr_bucket_mmap apr_bucket_mmap;
  639. /**
  640.  * A bucket referring to an mmap()ed file
  641.  */
  642. struct apr_bucket_mmap {
  643.     /** Number of buckets using this memory */
  644.     apr_bucket_refcount  refcount;
  645.     /** The mmap this sub_bucket refers to */
  646.     apr_mmap_t *mmap;
  647. };
  648. #endif
  649.  
  650. /** @see apr_bucket_file */
  651. typedef struct apr_bucket_file apr_bucket_file;
  652. /**
  653.  * A bucket referring to an file
  654.  */
  655. struct apr_bucket_file {
  656.     /** Number of buckets using this memory */
  657.     apr_bucket_refcount  refcount;
  658.     /** The file this bucket refers to */
  659.     apr_file_t *fd;
  660.     /** The pool into which any needed structures should
  661.      *  be created while reading from this file bucket */
  662.     apr_pool_t *readpool;
  663. #if APR_HAS_MMAP
  664.     /** Whether this bucket should be memory-mapped if
  665.      *  a caller tries to read from it */
  666.     int can_mmap;
  667. #endif /* APR_HAS_MMAP */
  668. };
  669.  
  670. /** @see apr_bucket_structs */
  671. typedef union apr_bucket_structs apr_bucket_structs;
  672. /**
  673.  * A union of all bucket structures so we know what
  674.  * the max size is.
  675.  */
  676. union apr_bucket_structs {
  677.     apr_bucket      b;      /**< Bucket */
  678.     apr_bucket_heap heap;   /**< Heap */
  679.     apr_bucket_pool pool;   /**< Pool */
  680. #if APR_HAS_MMAP
  681.     apr_bucket_mmap mmap;   /**< MMap */
  682. #endif
  683.     apr_bucket_file file;   /**< File */
  684. };
  685.  
  686. /**
  687.  * The amount that apr_bucket_alloc() should allocate in the common case.
  688.  * Note: this is twice as big as apr_bucket_structs to allow breathing
  689.  * room for third-party bucket types.
  690.  */
  691. #define APR_BUCKET_ALLOC_SIZE  APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
  692.  
  693. /*  *****  Bucket Brigade Functions  *****  */
  694. /**
  695.  * Create a new bucket brigade.  The bucket brigade is originally empty.
  696.  * @param p The pool to associate with the brigade.  Data is not allocated out
  697.  *          of the pool, but a cleanup is registered.
  698.  * @param list The bucket allocator to use
  699.  * @return The empty bucket brigade
  700.  */
  701. APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p,
  702.                                                      apr_bucket_alloc_t *list);
  703.  
  704. /**
  705.  * destroy an entire bucket brigade.  This includes destroying all of the
  706.  * buckets within the bucket brigade's bucket list. 
  707.  * @param b The bucket brigade to destroy
  708.  */
  709. APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b);
  710.  
  711. /**
  712.  * empty out an entire bucket brigade.  This includes destroying all of the
  713.  * buckets within the bucket brigade's bucket list.  This is similar to
  714.  * apr_brigade_destroy(), except that it does not deregister the brigade's
  715.  * pool cleanup function.
  716.  * @param data The bucket brigade to clean up
  717.  * @remark Generally, you should use apr_brigade_destroy().  This function
  718.  *         can be useful in situations where you have a single brigade that
  719.  *         you wish to reuse many times by destroying all of the buckets in
  720.  *         the brigade and putting new buckets into it later.
  721.  */
  722. APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data);
  723.  
  724. /**
  725.  * Split a bucket brigade into two, such that the given bucket is the
  726.  * first in the new bucket brigade. This function is useful when a
  727.  * filter wants to pass only the initial part of a brigade to the next
  728.  * filter.
  729.  * @param b The brigade to split
  730.  * @param e The first element of the new brigade
  731.  * @return The new brigade
  732.  */
  733. APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b,
  734.                                                     apr_bucket *e);
  735.  
  736. /**
  737.  * Partition a bucket brigade at a given offset (in bytes from the start of
  738.  * the brigade).  This is useful whenever a filter wants to use known ranges
  739.  * of bytes from the brigade; the ranges can even overlap.
  740.  * @param b The brigade to partition
  741.  * @param point The offset at which to partition the brigade
  742.  * @param after_point Returns a pointer to the first bucket after the partition
  743.  */
  744. APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b,
  745.                                                 apr_off_t point,
  746.                                                 apr_bucket **after_point);
  747.  
  748. #if APR_NOT_DONE_YET
  749. /**
  750.  * consume nbytes from beginning of b -- call apr_bucket_destroy as
  751.  * appropriate, and/or modify start on last element 
  752.  * @param b The brigade to consume data from
  753.  * @param nbytes The number of bytes to consume
  754.  */
  755. APU_DECLARE(void) apr_brigade_consume(apr_bucket_brigade *b,
  756.                                       apr_off_t nbytes);
  757. #endif
  758.  
  759. /**
  760.  * Return the total length of the brigade.
  761.  * @param bb The brigade to compute the length of
  762.  * @param read_all Read unknown-length buckets to force a size
  763.  * @param length Returns the length of the brigade, or -1 if the brigade has
  764.  *               buckets of indeterminate length and read_all is 0.
  765.  */
  766. APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
  767.                                              int read_all,
  768.                                              apr_off_t *length);
  769.  
  770. /**
  771.  * Take a bucket brigade and store the data in a flat char*
  772.  * @param bb The bucket brigade to create the char* from
  773.  * @param c The char* to write into
  774.  * @param len The maximum length of the char array. On return, it is the
  775.  *            actual length of the char array.
  776.  */
  777. APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb,
  778.                                               char *c,
  779.                                               apr_size_t *len);
  780.  
  781. /**
  782.  * Creates a pool-allocated string representing a flat bucket brigade
  783.  * @param bb The bucket brigade to create the char array from
  784.  * @param c On return, the allocated char array
  785.  * @param len On return, the length of the char array.
  786.  * @param pool The pool to allocate the string from.
  787.  */
  788. APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 
  789.                                                char **c,
  790.                                                apr_size_t *len,
  791.                                                apr_pool_t *pool);
  792.  
  793. /**
  794.  * Split a brigade to represent one LF line.
  795.  * @param bbOut The bucket brigade that will have the LF line appended to.
  796.  * @param bbIn The input bucket brigade to search for a LF-line.
  797.  * @param block The blocking mode to be used to split the line.
  798.  * @param maxbytes The maximum bytes to read.  If this many bytes are seen
  799.  *                 without a LF, the brigade will contain a partial line.
  800.  */
  801. APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut,
  802.                                                  apr_bucket_brigade *bbIn,
  803.                                                  apr_read_type_e block,
  804.                                                  apr_off_t maxbytes);
  805.  
  806. /**
  807.  * create an iovec of the elements in a bucket_brigade... return number 
  808.  * of elements used.  This is useful for writing to a file or to the
  809.  * network efficiently.
  810.  * @param b The bucket brigade to create the iovec from
  811.  * @param vec The iovec to create
  812.  * @param nvec The number of elements in the iovec. On return, it is the
  813.  *             number of iovec elements actually filled out.
  814.  */
  815. APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 
  816.                                                struct iovec *vec, int *nvec);
  817.  
  818. /**
  819.  * This function writes a list of strings into a bucket brigade. 
  820.  * @param b The bucket brigade to add to
  821.  * @param flush The flush function to use if the brigade is full
  822.  * @param ctx The structure to pass to the flush function
  823.  * @param va A list of strings to add
  824.  * @return APR_SUCCESS or error code.
  825.  */
  826. APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b,
  827.                                                apr_brigade_flush flush,
  828.                                                void *ctx,
  829.                                                va_list va);
  830.  
  831. /**
  832.  * This function writes a string into a bucket brigade.
  833.  * @param b The bucket brigade to add to
  834.  * @param flush The flush function to use if the brigade is full
  835.  * @param ctx The structure to pass to the flush function
  836.  * @param str The string to add
  837.  * @param nbyte The number of bytes to write
  838.  * @return APR_SUCCESS or error code
  839.  */
  840. APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b,
  841.                                             apr_brigade_flush flush, void *ctx,
  842.                                             const char *str, apr_size_t nbyte);
  843.  
  844. /**
  845.  * This function writes multiple strings into a bucket brigade.
  846.  * @param b The bucket brigade to add to
  847.  * @param flush The flush function to use if the brigade is full
  848.  * @param ctx The structure to pass to the flush function
  849.  * @param vec The strings to add (address plus length for each)
  850.  * @param nvec The number of entries in iovec
  851.  * @return APR_SUCCESS or error code
  852.  */
  853. APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b,
  854.                                              apr_brigade_flush flush,
  855.                                              void *ctx,
  856.                                              const struct iovec *vec,
  857.                                              apr_size_t nvec);
  858.  
  859. /**
  860.  * This function writes a string into a bucket brigade.
  861.  * @param bb The bucket brigade to add to
  862.  * @param flush The flush function to use if the brigade is full
  863.  * @param ctx The structure to pass to the flush function
  864.  * @param str The string to add
  865.  * @return APR_SUCCESS or error code
  866.  */
  867. APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb,
  868.                                            apr_brigade_flush flush, void *ctx,
  869.                                            const char *str);
  870.  
  871. /**
  872.  * This function writes a character into a bucket brigade.
  873.  * @param b The bucket brigade to add to
  874.  * @param flush The flush function to use if the brigade is full
  875.  * @param ctx The structure to pass to the flush function
  876.  * @param c The character to add
  877.  * @return APR_SUCCESS or error code
  878.  */
  879. APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b,
  880.                                            apr_brigade_flush flush, void *ctx,
  881.                                            const char c);
  882.  
  883. /**
  884.  * This function writes an unspecified number of strings into a bucket brigade.
  885.  * @param b The bucket brigade to add to
  886.  * @param flush The flush function to use if the brigade is full
  887.  * @param ctx The structure to pass to the flush function
  888.  * @param ... The strings to add
  889.  * @return APR_SUCCESS or error code
  890.  */
  891. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b,
  892.                                                      apr_brigade_flush flush,
  893.                                                      void *ctx, ...);
  894.  
  895. /**
  896.  * Evaluate a printf and put the resulting string at the end 
  897.  * of the bucket brigade.
  898.  * @param b The brigade to write to
  899.  * @param flush The flush function to use if the brigade is full
  900.  * @param ctx The structure to pass to the flush function
  901.  * @param fmt The format of the string to write
  902.  * @param ... The arguments to fill out the format
  903.  * @return APR_SUCCESS or error code
  904.  */
  905. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 
  906.                                                     apr_brigade_flush flush,
  907.                                                     void *ctx,
  908.                                                     const char *fmt, ...)
  909.         __attribute__((format(printf,4,5)));
  910.  
  911. /**
  912.  * Evaluate a printf and put the resulting string at the end 
  913.  * of the bucket brigade.
  914.  * @param b The brigade to write to
  915.  * @param flush The flush function to use if the brigade is full
  916.  * @param ctx The structure to pass to the flush function
  917.  * @param fmt The format of the string to write
  918.  * @param va The arguments to fill out the format
  919.  * @return APR_SUCCESS or error code
  920.  */
  921. APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 
  922.                                               apr_brigade_flush flush,
  923.                                               void *ctx,
  924.                                               const char *fmt, va_list va);
  925.  
  926. /*  *****  Bucket freelist functions *****  */
  927. /**
  928.  * Create a bucket allocator.
  929.  * @param p This pool's underlying apr_allocator_t is used to allocate memory
  930.  *          for the bucket allocator.  When the pool is destroyed, the bucket
  931.  *          allocator's cleanup routine will free all memory that has been
  932.  *          allocated from it.
  933.  * @remark  The reason the allocator gets its memory from the pool's
  934.  *          apr_allocator_t rather than from the pool itself is because
  935.  *          the bucket allocator will free large memory blocks back to the
  936.  *          allocator when it's done with them, thereby preventing memory
  937.  *          footprint growth that would occur if we allocated from the pool.
  938.  * @warning The allocator must never be used by more than one thread at a time.
  939.  */
  940. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p);
  941.  
  942. /**
  943.  * Create a bucket allocator.
  944.  * @param allocator This apr_allocator_t is used to allocate both the bucket
  945.  *          allocator and all memory handed out by the bucket allocator.  The
  946.  *          caller is responsible for destroying the bucket allocator and the
  947.  *          apr_allocator_t -- no automatic cleanups will happen.
  948.  * @warning The allocator must never be used by more than one thread at a time.
  949.  */
  950. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator);
  951.  
  952. /**
  953.  * Destroy a bucket allocator.
  954.  * @param list The allocator to be destroyed
  955.  */
  956. APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list);
  957.  
  958. /**
  959.  * Allocate memory for use by the buckets.
  960.  * @param size The amount to allocate.
  961.  * @param list The allocator from which to allocate the memory.
  962.  */
  963. APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list);
  964.  
  965. /**
  966.  * Free memory previously allocated with apr_bucket_alloc().
  967.  * @param block The block of memory to be freed.
  968.  */
  969. APU_DECLARE_NONSTD(void) apr_bucket_free(void *block);
  970.  
  971.  
  972. /*  *****  Bucket Functions  *****  */
  973. /**
  974.  * Free the resources used by a bucket. If multiple buckets refer to
  975.  * the same resource it is freed when the last one goes away.
  976.  * @see apr_bucket_delete()
  977.  * @param e The bucket to destroy
  978.  */
  979. #define apr_bucket_destroy(e) do {                    \
  980.         (e)->type->destroy((e)->data);                    \
  981.         (e)->free(e);                            \
  982.     } while (0)
  983.  
  984. /**
  985.  * Delete a bucket by removing it from its brigade (if any) and then
  986.  * destroying it.
  987.  * @remark This mainly acts as an aid in avoiding code verbosity.  It is
  988.  * the preferred exact equivalent to:
  989.  * <pre>
  990.  *      APR_BUCKET_REMOVE(e);
  991.  *      apr_bucket_destroy(e);
  992.  * </pre>
  993.  * @param e The bucket to delete
  994.  */
  995. #define apr_bucket_delete(e) do {                    \
  996.         APR_BUCKET_REMOVE(e);                        \
  997.         apr_bucket_destroy(e);                        \
  998.     } while (0)
  999.  
  1000. /**
  1001.  * read the data from the bucket
  1002.  * @param e The bucket to read from
  1003.  * @param str The location to store the data in
  1004.  * @param len The amount of data read
  1005.  * @param block Whether the read function blocks
  1006.  */
  1007. #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
  1008.  
  1009. /**
  1010.  * Setaside data so that stack data is not destroyed on returning from
  1011.  * the function
  1012.  * @param e The bucket to setaside
  1013.  * @param p The pool to setaside into
  1014.  */
  1015. #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
  1016.  
  1017. /**
  1018.  * Split one bucket in two.
  1019.  * @param e The bucket to split
  1020.  * @param point The offset to split the bucket at
  1021.  */
  1022. #define apr_bucket_split(e,point) (e)->type->split(e, point)
  1023.  
  1024. /**
  1025.  * Copy a bucket.
  1026.  * @param e The bucket to copy
  1027.  * @param c Returns a pointer to the new bucket
  1028.  */
  1029. #define apr_bucket_copy(e,c) (e)->type->copy(e, c)
  1030.  
  1031. /* Bucket type handling */
  1032.  
  1033. /**
  1034.  * This function simply returns APR_SUCCESS to denote that the bucket does
  1035.  * not require anything to happen for its setaside() function. This is
  1036.  * appropriate for buckets that have "immortal" data -- the data will live
  1037.  * at least as long as the bucket.
  1038.  * @param data The bucket to setaside
  1039.  * @param pool The pool defining the desired lifetime of the bucket data
  1040.  * @return APR_SUCCESS
  1041.  */ 
  1042. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data,
  1043.                                                           apr_pool_t *pool);
  1044.  
  1045. /**
  1046.  * A place holder function that signifies that the setaside function was not
  1047.  * implemented for this bucket
  1048.  * @param data The bucket to setaside
  1049.  * @param pool The pool defining the desired lifetime of the bucket data
  1050.  * @return APR_ENOTIMPL
  1051.  */ 
  1052. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data,
  1053.                                                              apr_pool_t *pool);
  1054.  
  1055. /**
  1056.  * A place holder function that signifies that the split function was not
  1057.  * implemented for this bucket
  1058.  * @param data The bucket to split
  1059.  * @param point The location to split the bucket
  1060.  * @return APR_ENOTIMPL
  1061.  */ 
  1062. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data,
  1063.                                                           apr_size_t point);
  1064.  
  1065. /**
  1066.  * A place holder function that signifies that the copy function was not
  1067.  * implemented for this bucket
  1068.  * @param e The bucket to copy
  1069.  * @param c Returns a pointer to the new bucket
  1070.  * @return APR_ENOTIMPL
  1071.  */
  1072. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e,
  1073.                                                          apr_bucket **c);
  1074.  
  1075. /**
  1076.  * A place holder function that signifies that this bucket does not need
  1077.  * to do anything special to be destroyed.  That's only the case for buckets
  1078.  * that either have no data (metadata buckets) or buckets whose data pointer
  1079.  * points to something that's not a bucket-type-specific structure, as with
  1080.  * simple buckets where data points to a string and pipe buckets where data
  1081.  * points directly to the apr_file_t.
  1082.  * @param data The bucket data to destroy
  1083.  */ 
  1084. APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data);
  1085.  
  1086. /**
  1087.  * There is no apr_bucket_destroy_notimpl, because destruction is required
  1088.  * to be implemented (it could be a noop, but only if that makes sense for
  1089.  * the bucket type)
  1090.  */
  1091.  
  1092. /* There is no apr_bucket_read_notimpl, because it is a required function
  1093.  */
  1094.  
  1095.  
  1096. /* All of the bucket types implemented by the core */
  1097. /**
  1098.  * The flush bucket type.  This signifies that all data should be flushed to
  1099.  * the next filter.  The flush bucket should be sent with the other buckets.
  1100.  */
  1101. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
  1102. /**
  1103.  * The EOS bucket type.  This signifies that there will be no more data, ever.
  1104.  * All filters MUST send all data to the next filter when they receive a
  1105.  * bucket of this type
  1106.  */
  1107. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
  1108. /**
  1109.  * The FILE bucket type.  This bucket represents a file on disk
  1110.  */
  1111. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
  1112. /**
  1113.  * The HEAP bucket type.  This bucket represents a data allocated from the
  1114.  * heap.
  1115.  */
  1116. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
  1117. #if APR_HAS_MMAP
  1118. /**
  1119.  * The MMAP bucket type.  This bucket represents an MMAP'ed file
  1120.  */
  1121. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
  1122. #endif
  1123. /**
  1124.  * The POOL bucket type.  This bucket represents a data that was allocated
  1125.  * from a pool.  IF this bucket is still available when the pool is cleared,
  1126.  * the data is copied on to the heap.
  1127.  */
  1128. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
  1129. /**
  1130.  * The PIPE bucket type.  This bucket represents a pipe to another program.
  1131.  */
  1132. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
  1133. /**
  1134.  * The IMMORTAL bucket type.  This bucket represents a segment of data that
  1135.  * the creator is willing to take responsibility for.  The core will do
  1136.  * nothing with the data in an immortal bucket
  1137.  */
  1138. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
  1139. /**
  1140.  * The TRANSIENT bucket type.  This bucket represents a data allocated off
  1141.  * the stack.  When the setaside function is called, this data is copied on
  1142.  * to the heap
  1143.  */
  1144. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
  1145. /**
  1146.  * The SOCKET bucket type.  This bucket represents a socket to another machine
  1147.  */
  1148. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;
  1149.  
  1150.  
  1151. /*  *****  Simple buckets  *****  */
  1152.  
  1153. /**
  1154.  * Split a simple bucket into two at the given point.  Most non-reference
  1155.  * counting buckets that allow multiple references to the same block of
  1156.  * data (eg transient and immortal) will use this as their split function
  1157.  * without any additional type-specific handling.
  1158.  * @param b The bucket to be split
  1159.  * @param point The offset of the first byte in the new bucket
  1160.  * @return APR_EINVAL if the point is not within the bucket;
  1161.  *         APR_ENOMEM if allocation failed;
  1162.  *         or APR_SUCCESS
  1163.  */
  1164. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
  1165.                                                          apr_size_t point);
  1166.  
  1167. /**
  1168.  * Copy a simple bucket.  Most non-reference-counting buckets that allow
  1169.  * multiple references to the same block of data (eg transient and immortal)
  1170.  * will use this as their copy function without any additional type-specific
  1171.  * handling.
  1172.  * @param a The bucket to copy
  1173.  * @param b Returns a pointer to the new bucket
  1174.  * @return APR_ENOMEM if allocation failed;
  1175.  *         or APR_SUCCESS
  1176.  */
  1177. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
  1178.                                                         apr_bucket **b);
  1179.  
  1180.  
  1181. /*  *****  Shared, reference-counted buckets  *****  */
  1182.  
  1183. /**
  1184.  * Initialize a bucket containing reference-counted data that may be
  1185.  * shared. The caller must allocate the bucket if necessary and
  1186.  * initialize its type-dependent fields, and allocate and initialize
  1187.  * its own private data structure. This function should only be called
  1188.  * by type-specific bucket creation functions.
  1189.  * @param b The bucket to initialize
  1190.  * @param data A pointer to the private data structure
  1191.  *             with the reference count at the start
  1192.  * @param start The start of the data in the bucket
  1193.  *              relative to the private base pointer
  1194.  * @param length The length of the data in the bucket
  1195.  * @return The new bucket, or NULL if allocation failed
  1196.  */
  1197. APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
  1198.                                  apr_off_t start, 
  1199.                                                  apr_size_t length);
  1200.  
  1201. /**
  1202.  * Decrement the refcount of the data in the bucket. This function
  1203.  * should only be called by type-specific bucket destruction functions.
  1204.  * @param data The private data pointer from the bucket to be destroyed
  1205.  * @return TRUE or FALSE; TRUE if the reference count is now
  1206.  *         zero, indicating that the shared resource itself can
  1207.  *         be destroyed by the caller.
  1208.  */
  1209. APU_DECLARE(int) apr_bucket_shared_destroy(void *data);
  1210.  
  1211. /**
  1212.  * Split a bucket into two at the given point, and adjust the refcount
  1213.  * to the underlying data. Most reference-counting bucket types will
  1214.  * be able to use this function as their split function without any
  1215.  * additional type-specific handling.
  1216.  * @param b The bucket to be split
  1217.  * @param point The offset of the first byte in the new bucket
  1218.  * @return APR_EINVAL if the point is not within the bucket;
  1219.  *         APR_ENOMEM if allocation failed;
  1220.  *         or APR_SUCCESS
  1221.  */
  1222. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
  1223.                                                          apr_size_t point);
  1224.  
  1225. /**
  1226.  * Copy a refcounted bucket, incrementing the reference count. Most
  1227.  * reference-counting bucket types will be able to use this function
  1228.  * as their copy function without any additional type-specific handling.
  1229.  * @param a The bucket to copy
  1230.  * @param b Returns a pointer to the new bucket
  1231.  * @return APR_ENOMEM if allocation failed;
  1232.            or APR_SUCCESS
  1233.  */
  1234. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
  1235.                                                         apr_bucket **b);
  1236.  
  1237.  
  1238. /*  *****  Functions to Create Buckets of varying types  *****  */
  1239. /*
  1240.  * Each bucket type foo has two initialization functions:
  1241.  * apr_bucket_foo_make which sets up some already-allocated memory as a
  1242.  * bucket of type foo; and apr_bucket_foo_create which allocates memory
  1243.  * for the bucket, calls apr_bucket_make_foo, and initializes the
  1244.  * bucket's list pointers. The apr_bucket_foo_make functions are used
  1245.  * inside the bucket code to change the type of buckets in place;
  1246.  * other code should call apr_bucket_foo_create. All the initialization
  1247.  * functions change nothing if they fail.
  1248.  */
  1249.  
  1250. /**
  1251.  * Create an End of Stream bucket.  This indicates that there is no more data
  1252.  * coming from down the filter stack.  All filters should flush at this point.
  1253.  * @param list The freelist from which this bucket should be allocated
  1254.  * @return The new bucket, or NULL if allocation failed
  1255.  */
  1256. APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list);
  1257.  
  1258. /**
  1259.  * Make the bucket passed in an EOS bucket.  This indicates that there is no 
  1260.  * more data coming from down the filter stack.  All filters should flush at 
  1261.  * this point.
  1262.  * @param b The bucket to make into an EOS bucket
  1263.  * @return The new bucket, or NULL if allocation failed
  1264.  */
  1265. APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);
  1266.  
  1267. /**
  1268.  * Create a flush  bucket.  This indicates that filters should flush their
  1269.  * data.  There is no guarantee that they will flush it, but this is the
  1270.  * best we can do.
  1271.  * @param list The freelist from which this bucket should be allocated
  1272.  * @return The new bucket, or NULL if allocation failed
  1273.  */
  1274. APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list);
  1275.  
  1276. /**
  1277.  * Make the bucket passed in a FLUSH  bucket.  This indicates that filters 
  1278.  * should flush their data.  There is no guarantee that they will flush it, 
  1279.  * but this is the best we can do.
  1280.  * @param b The bucket to make into a FLUSH bucket
  1281.  * @return The new bucket, or NULL if allocation failed
  1282.  */
  1283. APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);
  1284.  
  1285. /**
  1286.  * Create a bucket referring to long-lived data.
  1287.  * @param buf The data to insert into the bucket
  1288.  * @param nbyte The size of the data to insert.
  1289.  * @param list The freelist from which this bucket should be allocated
  1290.  * @return The new bucket, or NULL if allocation failed
  1291.  */
  1292. APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 
  1293.                                                      apr_size_t nbyte,
  1294.                                                      apr_bucket_alloc_t *list);
  1295.  
  1296. /**
  1297.  * Make the bucket passed in a bucket refer to long-lived data
  1298.  * @param b The bucket to make into a IMMORTAL bucket
  1299.  * @param buf The data to insert into the bucket
  1300.  * @param nbyte The size of the data to insert.
  1301.  * @return The new bucket, or NULL if allocation failed
  1302.  */
  1303. APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 
  1304.                                                    const char *buf, 
  1305.                                                    apr_size_t nbyte);
  1306.  
  1307. /**
  1308.  * Create a bucket referring to data on the stack.
  1309.  * @param buf The data to insert into the bucket
  1310.  * @param nbyte The size of the data to insert.
  1311.  * @param list The freelist from which this bucket should be allocated
  1312.  * @return The new bucket, or NULL if allocation failed
  1313.  */
  1314. APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 
  1315.                                                       apr_size_t nbyte,
  1316.                                                       apr_bucket_alloc_t *list);
  1317.  
  1318. /**
  1319.  * Make the bucket passed in a bucket refer to stack data
  1320.  * @param b The bucket to make into a TRANSIENT bucket
  1321.  * @param buf The data to insert into the bucket
  1322.  * @param nbyte The size of the data to insert.
  1323.  * @return The new bucket, or NULL if allocation failed
  1324.  */
  1325. APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 
  1326.                                                     const char *buf,
  1327.                                                     apr_size_t nbyte);
  1328.  
  1329. /**
  1330.  * Create a bucket referring to memory on the heap. If the caller asks
  1331.  * for the data to be copied, this function always allocates 4K of
  1332.  * memory so that more data can be added to the bucket without
  1333.  * requiring another allocation. Therefore not all the data may be put
  1334.  * into the bucket. If copying is not requested then the bucket takes
  1335.  * over responsibility for free()ing the memory.
  1336.  * @param buf The buffer to insert into the bucket
  1337.  * @param nbyte The size of the buffer to insert.
  1338.  * @param free_func Function to use to free the data; NULL indicates that the
  1339.  *                  bucket should make a copy of the data
  1340.  * @param list The freelist from which this bucket should be allocated
  1341.  * @return The new bucket, or NULL if allocation failed
  1342.  */
  1343. APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 
  1344.                                                  apr_size_t nbyte,
  1345.                                                  void (*free_func)(void *data),
  1346.                                                  apr_bucket_alloc_t *list);
  1347. /**
  1348.  * Make the bucket passed in a bucket refer to heap data
  1349.  * @param b The bucket to make into a HEAP bucket
  1350.  * @param buf The buffer to insert into the bucket
  1351.  * @param nbyte The size of the buffer to insert.
  1352.  * @param free_func Function to use to free the data; NULL indicates that the
  1353.  *                  bucket should make a copy of the data
  1354.  * @return The new bucket, or NULL if allocation failed
  1355.  */
  1356. APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf,
  1357.                                                apr_size_t nbyte,
  1358.                                                void (*free_func)(void *data));
  1359.  
  1360. /**
  1361.  * Create a bucket referring to memory allocated from a pool.
  1362.  *
  1363.  * @param buf The buffer to insert into the bucket
  1364.  * @param length The number of bytes referred to by this bucket
  1365.  * @param pool The pool the memory was allocated from
  1366.  * @param list The freelist from which this bucket should be allocated
  1367.  * @return The new bucket, or NULL if allocation failed
  1368.  */
  1369. APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 
  1370.                                                  apr_size_t length,
  1371.                                                  apr_pool_t *pool,
  1372.                                                  apr_bucket_alloc_t *list);
  1373.  
  1374. /**
  1375.  * Make the bucket passed in a bucket refer to pool data
  1376.  * @param b The bucket to make into a pool bucket
  1377.  * @param buf The buffer to insert into the bucket
  1378.  * @param length The number of bytes referred to by this bucket
  1379.  * @param pool The pool the memory was allocated from
  1380.  * @return The new bucket, or NULL if allocation failed
  1381.  */
  1382. APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf,
  1383.                                                apr_size_t length, 
  1384.                                                apr_pool_t *pool);
  1385.  
  1386. #if APR_HAS_MMAP
  1387. /**
  1388.  * Create a bucket referring to mmap()ed memory.
  1389.  * @param mm The mmap to insert into the bucket
  1390.  * @param start The offset of the first byte in the mmap
  1391.  *              that this bucket refers to
  1392.  * @param length The number of bytes referred to by this bucket
  1393.  * @param list The freelist from which this bucket should be allocated
  1394.  * @return The new bucket, or NULL if allocation failed
  1395.  */
  1396. APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 
  1397.                                                  apr_off_t start,
  1398.                                                  apr_size_t length,
  1399.                                                  apr_bucket_alloc_t *list);
  1400.  
  1401. /**
  1402.  * Make the bucket passed in a bucket refer to an MMAP'ed file
  1403.  * @param b The bucket to make into a MMAP bucket
  1404.  * @param mm The mmap to insert into the bucket
  1405.  * @param start The offset of the first byte in the mmap
  1406.  *              that this bucket refers to
  1407.  * @param length The number of bytes referred to by this bucket
  1408.  * @return The new bucket, or NULL if allocation failed
  1409.  */
  1410. APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm,
  1411.                                                apr_off_t start, 
  1412.                                                apr_size_t length);
  1413. #endif
  1414.  
  1415. /**
  1416.  * Create a bucket referring to a socket.
  1417.  * @param thissock The socket to put in the bucket
  1418.  * @param list The freelist from which this bucket should be allocated
  1419.  * @return The new bucket, or NULL if allocation failed
  1420.  */
  1421. APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock,
  1422.                                                    apr_bucket_alloc_t *list);
  1423. /**
  1424.  * Make the bucket passed in a bucket refer to a socket
  1425.  * @param b The bucket to make into a SOCKET bucket
  1426.  * @param thissock The socket to put in the bucket
  1427.  * @return The new bucket, or NULL if allocation failed
  1428.  */
  1429. APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 
  1430.                                                  apr_socket_t *thissock);
  1431.  
  1432. /**
  1433.  * Create a bucket referring to a pipe.
  1434.  * @param thispipe The pipe to put in the bucket
  1435.  * @param list The freelist from which this bucket should be allocated
  1436.  * @return The new bucket, or NULL if allocation failed
  1437.  */
  1438. APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe,
  1439.                                                  apr_bucket_alloc_t *list);
  1440.  
  1441. /**
  1442.  * Make the bucket passed in a bucket refer to a pipe
  1443.  * @param b The bucket to make into a PIPE bucket
  1444.  * @param thispipe The pipe to put in the bucket
  1445.  * @return The new bucket, or NULL if allocation failed
  1446.  */
  1447. APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 
  1448.                                                apr_file_t *thispipe);
  1449.  
  1450. /**
  1451.  * Create a bucket referring to a file.
  1452.  * @param fd The file to put in the bucket
  1453.  * @param offset The offset where the data of interest begins in the file
  1454.  * @param len The amount of data in the file we are interested in
  1455.  * @param p The pool into which any needed structures should be created
  1456.  *          while reading from this file bucket
  1457.  * @param list The freelist from which this bucket should be allocated
  1458.  * @return The new bucket, or NULL if allocation failed
  1459.  */
  1460. APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd,
  1461.                                                  apr_off_t offset,
  1462.                                                  apr_size_t len, 
  1463.                                                  apr_pool_t *p,
  1464.                                                  apr_bucket_alloc_t *list);
  1465.  
  1466. /**
  1467.  * Make the bucket passed in a bucket refer to a file
  1468.  * @param b The bucket to make into a FILE bucket
  1469.  * @param fd The file to put in the bucket
  1470.  * @param offset The offset where the data of interest begins in the file
  1471.  * @param len The amount of data in the file we are interested in
  1472.  * @param p The pool into which any needed structures should be created
  1473.  *          while reading from this file bucket
  1474.  * @return The new bucket, or NULL if allocation failed
  1475.  */
  1476. APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
  1477.                                                apr_off_t offset,
  1478.                                                apr_size_t len, apr_pool_t *p);
  1479.  
  1480. /**
  1481.  * Enable or disable memory-mapping for a FILE bucket (default is enabled)
  1482.  * @param b The bucket
  1483.  * @param enabled Whether memory-mapping should be enabled
  1484.  * @return APR_SUCCESS normally, or an error code if the operation fails
  1485.  */
  1486. APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b,
  1487.                                                       int enabled);
  1488.  
  1489. /** @} */
  1490. #ifdef __cplusplus
  1491. }
  1492. #endif
  1493.  
  1494. #endif /* !APR_BUCKETS_H */
  1495.