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