Main Page | Modules | Namespace List | Data Structures | File List | Data Fields | Globals | Related Pages

include/apr_buckets.h

Go to the documentation of this file.
00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00021 #ifndef APR_BUCKETS_H 00022 #define APR_BUCKETS_H 00023 00024 #if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG) 00025 #define APR_RING_DEBUG 00026 #endif 00027 00028 #include "apu.h" 00029 #include "apr_network_io.h" 00030 #include "apr_file_io.h" 00031 #include "apr_general.h" 00032 #include "apr_mmap.h" 00033 #include "apr_errno.h" 00034 #include "apr_ring.h" 00035 #include "apr.h" 00036 #if APR_HAVE_SYS_UIO_H 00037 #include <sys/uio.h> /* for struct iovec */ 00038 #endif 00039 #if APR_HAVE_STDARG_H 00040 #include <stdarg.h> 00041 #endif 00042 00043 #ifdef __cplusplus 00044 extern "C" { 00045 #endif 00046 00054 #define APR_BUCKET_BUFF_SIZE 8000 00055 00057 typedef enum { 00058 APR_BLOCK_READ, 00059 APR_NONBLOCK_READ 00060 } apr_read_type_e; 00061 00114 /* 00115 * Forward declaration of the main types. 00116 */ 00117 00119 typedef struct apr_bucket_brigade apr_bucket_brigade; 00121 typedef struct apr_bucket apr_bucket; 00123 typedef struct apr_bucket_alloc_t apr_bucket_alloc_t; 00124 00126 typedef struct apr_bucket_type_t apr_bucket_type_t; 00127 00131 struct apr_bucket_type_t { 00135 const char *name; 00140 int num_func; 00151 enum { 00153 APR_BUCKET_DATA = 0, 00155 APR_BUCKET_METADATA = 1 00156 } is_metadata; 00164 void (*destroy)(void *data); 00165 00176 apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 00177 apr_read_type_e block); 00178 00192 apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool); 00193 00203 apr_status_t (*split)(apr_bucket *e, apr_size_t point); 00204 00211 apr_status_t (*copy)(apr_bucket *e, apr_bucket **c); 00212 00213 }; 00214 00224 struct apr_bucket { 00226 APR_RING_ENTRY(apr_bucket) link; 00228 const apr_bucket_type_t *type; 00234 apr_size_t length; 00242 apr_off_t start; 00244 void *data; 00252 void (*free)(void *e); 00254 apr_bucket_alloc_t *list; 00255 }; 00256 00258 struct apr_bucket_brigade { 00264 apr_pool_t *p; 00266 /* 00267 * The apr_bucket_list structure doesn't actually need a name tag 00268 * because it has no existence independent of struct apr_bucket_brigade; 00269 * the ring macros are designed so that you can leave the name tag 00270 * argument empty in this situation but apparently the Windows compiler 00271 * doesn't like that. 00272 */ 00273 APR_RING_HEAD(apr_bucket_list, apr_bucket) list; 00275 apr_bucket_alloc_t *bucket_alloc; 00276 }; 00277 00278 00282 typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx); 00283 00284 /* 00285 * define APR_BUCKET_DEBUG if you want your brigades to be checked for 00286 * validity at every possible instant. this will slow your code down 00287 * substantially but is a very useful debugging tool. 00288 */ 00289 #ifdef APR_BUCKET_DEBUG 00290 00291 #define APR_BRIGADE_CHECK_CONSISTENCY(b) \ 00292 APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link) 00293 00294 #define APR_BUCKET_CHECK_CONSISTENCY(e) \ 00295 APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link) 00296 00297 #else 00304 #define APR_BRIGADE_CHECK_CONSISTENCY(b) 00311 #define APR_BUCKET_CHECK_CONSISTENCY(e) 00312 #endif 00313 00314 00331 #define APR_BRIGADE_SENTINEL(b) APR_RING_SENTINEL(&(b)->list, apr_bucket, link) 00332 00338 #define APR_BRIGADE_EMPTY(b) APR_RING_EMPTY(&(b)->list, apr_bucket, link) 00339 00345 #define APR_BRIGADE_FIRST(b) APR_RING_FIRST(&(b)->list) 00351 #define APR_BRIGADE_LAST(b) APR_RING_LAST(&(b)->list) 00352 00358 #define APR_BRIGADE_INSERT_HEAD(b, e) do { \ 00359 apr_bucket *ap__b = (e); \ 00360 APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link); \ 00361 APR_BRIGADE_CHECK_CONSISTENCY((b)); \ 00362 } while (0) 00363 00369 #define APR_BRIGADE_INSERT_TAIL(b, e) do { \ 00370 apr_bucket *ap__b = (e); \ 00371 APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link); \ 00372 APR_BRIGADE_CHECK_CONSISTENCY((b)); \ 00373 } while (0) 00374 00380 #define APR_BRIGADE_CONCAT(a, b) do { \ 00381 APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link); \ 00382 APR_BRIGADE_CHECK_CONSISTENCY((a)); \ 00383 } while (0) 00384 00390 #define APR_BRIGADE_PREPEND(a, b) do { \ 00391 APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link); \ 00392 APR_BRIGADE_CHECK_CONSISTENCY((a)); \ 00393 } while (0) 00394 00400 #define APR_BUCKET_INSERT_BEFORE(a, b) do { \ 00401 apr_bucket *ap__a = (a), *ap__b = (b); \ 00402 APR_RING_INSERT_BEFORE(ap__a, ap__b, link); \ 00403 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \ 00404 } while (0) 00405 00411 #define APR_BUCKET_INSERT_AFTER(a, b) do { \ 00412 apr_bucket *ap__a = (a), *ap__b = (b); \ 00413 APR_RING_INSERT_AFTER(ap__a, ap__b, link); \ 00414 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \ 00415 } while (0) 00416 00422 #define APR_BUCKET_NEXT(e) APR_RING_NEXT((e), link) 00423 00428 #define APR_BUCKET_PREV(e) APR_RING_PREV((e), link) 00429 00434 #define APR_BUCKET_REMOVE(e) APR_RING_REMOVE((e), link) 00435 00440 #define APR_BUCKET_INIT(e) APR_RING_ELEM_INIT((e), link) 00441 00448 #define APR_BUCKET_IS_METADATA(e) ((e)->type->is_metadata) 00449 00455 #define APR_BUCKET_IS_FLUSH(e) ((e)->type == &apr_bucket_type_flush) 00456 00461 #define APR_BUCKET_IS_EOS(e) ((e)->type == &apr_bucket_type_eos) 00462 00467 #define APR_BUCKET_IS_FILE(e) ((e)->type == &apr_bucket_type_file) 00468 00473 #define APR_BUCKET_IS_PIPE(e) ((e)->type == &apr_bucket_type_pipe) 00474 00479 #define APR_BUCKET_IS_SOCKET(e) ((e)->type == &apr_bucket_type_socket) 00480 00485 #define APR_BUCKET_IS_HEAP(e) ((e)->type == &apr_bucket_type_heap) 00486 00491 #define APR_BUCKET_IS_TRANSIENT(e) ((e)->type == &apr_bucket_type_transient) 00492 00497 #define APR_BUCKET_IS_IMMORTAL(e) ((e)->type == &apr_bucket_type_immortal) 00498 #if APR_HAS_MMAP 00499 00504 #define APR_BUCKET_IS_MMAP(e) ((e)->type == &apr_bucket_type_mmap) 00505 #endif 00506 00511 #define APR_BUCKET_IS_POOL(e) ((e)->type == &apr_bucket_type_pool) 00512 00513 /* 00514 * General-purpose reference counting for the various bucket types. 00515 * 00516 * Any bucket type that keeps track of the resources it uses (i.e. 00517 * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to 00518 * attach a reference count to the resource so that it can be freed 00519 * when the last bucket that uses it goes away. Resource-sharing may 00520 * occur because of bucket splits or buckets that refer to globally 00521 * cached data. */ 00522 00524 typedef struct apr_bucket_refcount apr_bucket_refcount; 00531 struct apr_bucket_refcount { 00533 int refcount; 00534 }; 00535 00536 /* ***** Reference-counted bucket types ***** */ 00537 00539 typedef struct apr_bucket_heap apr_bucket_heap; 00543 struct apr_bucket_heap { 00545 apr_bucket_refcount refcount; 00549 char *base; 00551 apr_size_t alloc_len; 00553 void (*free_func)(void *data); 00554 }; 00555 00557 typedef struct apr_bucket_pool apr_bucket_pool; 00561 struct apr_bucket_pool { 00573 apr_bucket_heap heap; 00579 const char *base; 00586 apr_pool_t *pool; 00590 apr_bucket_alloc_t *list; 00591 }; 00592 00593 #if APR_HAS_MMAP 00594 00595 typedef struct apr_bucket_mmap apr_bucket_mmap; 00599 struct apr_bucket_mmap { 00601 apr_bucket_refcount refcount; 00603 apr_mmap_t *mmap; 00604 }; 00605 #endif 00606 00608 typedef struct apr_bucket_file apr_bucket_file; 00612 struct apr_bucket_file { 00614 apr_bucket_refcount refcount; 00616 apr_file_t *fd; 00619 apr_pool_t *readpool; 00620 #if APR_HAS_MMAP 00621 00623 int can_mmap; 00624 #endif /* APR_HAS_MMAP */ 00625 }; 00626 00628 typedef union apr_bucket_structs apr_bucket_structs; 00633 union apr_bucket_structs { 00634 apr_bucket b; 00635 apr_bucket_heap heap; 00636 apr_bucket_pool pool; 00637 #if APR_HAS_MMAP 00638 apr_bucket_mmap mmap; 00639 #endif 00640 apr_bucket_file file; 00641 }; 00642 00648 #define APR_BUCKET_ALLOC_SIZE APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs)) 00649 00650 /* ***** Bucket Brigade Functions ***** */ 00658 APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p, 00659 apr_bucket_alloc_t *list); 00660 00666 APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b); 00667 00679 APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data); 00680 00690 APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b, 00691 apr_bucket *e); 00692 00705 APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b, 00706 apr_off_t point, 00707 apr_bucket **after_point); 00708 00716 APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb, 00717 int read_all, 00718 apr_off_t *length); 00719 00727 APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb, 00728 char *c, 00729 apr_size_t *len); 00730 00738 APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 00739 char **c, 00740 apr_size_t *len, 00741 apr_pool_t *pool); 00742 00751 APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut, 00752 apr_bucket_brigade *bbIn, 00753 apr_read_type_e block, 00754 apr_off_t maxbytes); 00755 00765 APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 00766 struct iovec *vec, int *nvec); 00767 00776 APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b, 00777 apr_brigade_flush flush, 00778 void *ctx, 00779 va_list va); 00780 00790 APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b, 00791 apr_brigade_flush flush, void *ctx, 00792 const char *str, apr_size_t nbyte); 00793 00803 APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b, 00804 apr_brigade_flush flush, 00805 void *ctx, 00806 const struct iovec *vec, 00807 apr_size_t nvec); 00808 00817 APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb, 00818 apr_brigade_flush flush, void *ctx, 00819 const char *str); 00820 00829 APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b, 00830 apr_brigade_flush flush, void *ctx, 00831 const char c); 00832 00841 APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b, 00842 apr_brigade_flush flush, 00843 void *ctx, ...); 00844 00855 APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 00856 apr_brigade_flush flush, 00857 void *ctx, 00858 const char *fmt, ...) 00859 __attribute__((format(printf,4,5))); 00860 00871 APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 00872 apr_brigade_flush flush, 00873 void *ctx, 00874 const char *fmt, va_list va); 00875 00888 APU_DECLARE(apr_bucket *) apr_brigade_insert_file(apr_bucket_brigade *bb, 00889 apr_file_t *f, 00890 apr_off_t start, 00891 apr_off_t len, 00892 apr_pool_t *p); 00893 00894 00895 00896 /* ***** Bucket freelist functions ***** */ 00910 APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p); 00911 00920 APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator); 00921 00926 APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list); 00927 00933 APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list); 00934 00939 APU_DECLARE_NONSTD(void) apr_bucket_free(void *block); 00940 00941 00942 /* ***** Bucket Functions ***** */ 00949 #define apr_bucket_destroy(e) do { \ 00950 (e)->type->destroy((e)->data); \ 00951 (e)->free(e); \ 00952 } while (0) 00953 00965 #define apr_bucket_delete(e) do { \ 00966 APR_BUCKET_REMOVE(e); \ 00967 apr_bucket_destroy(e); \ 00968 } while (0) 00969 00977 #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block) 00978 00985 #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p) 00986 00992 #define apr_bucket_split(e,point) (e)->type->split(e, point) 00993 00999 #define apr_bucket_copy(e,c) (e)->type->copy(e, c) 01000 01001 /* Bucket type handling */ 01002 01012 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data, 01013 apr_pool_t *pool); 01014 01022 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data, 01023 apr_pool_t *pool); 01024 01032 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data, 01033 apr_size_t point); 01034 01042 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e, 01043 apr_bucket **c); 01044 01054 APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data); 01055 01062 /* There is no apr_bucket_read_notimpl, because it is a required function 01063 */ 01064 01065 01066 /* All of the bucket types implemented by the core */ 01071 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush; 01077 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos; 01081 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file; 01086 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap; 01087 #if APR_HAS_MMAP 01091 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap; 01092 #endif 01098 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool; 01102 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe; 01108 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal; 01114 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient; 01118 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket; 01119 01120 01121 /* ***** Simple buckets ***** */ 01122 01134 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b, 01135 apr_size_t point); 01136 01147 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a, 01148 apr_bucket **b); 01149 01150 01151 /* ***** Shared, reference-counted buckets ***** */ 01152 01167 APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data, 01168 apr_off_t start, 01169 apr_size_t length); 01170 01179 APU_DECLARE(int) apr_bucket_shared_destroy(void *data); 01180 01192 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b, 01193 apr_size_t point); 01194 01204 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a, 01205 apr_bucket **b); 01206 01207 01208 /* ***** Functions to Create Buckets of varying types ***** */ 01209 /* 01210 * Each bucket type foo has two initialization functions: 01211 * apr_bucket_foo_make which sets up some already-allocated memory as a 01212 * bucket of type foo; and apr_bucket_foo_create which allocates memory 01213 * for the bucket, calls apr_bucket_make_foo, and initializes the 01214 * bucket's list pointers. The apr_bucket_foo_make functions are used 01215 * inside the bucket code to change the type of buckets in place; 01216 * other code should call apr_bucket_foo_create. All the initialization 01217 * functions change nothing if they fail. 01218 */ 01219 01226 APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list); 01227 01235 APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b); 01236 01244 APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list); 01245 01253 APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b); 01254 01262 APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 01263 apr_size_t nbyte, 01264 apr_bucket_alloc_t *list); 01265 01273 APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 01274 const char *buf, 01275 apr_size_t nbyte); 01276 01284 APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 01285 apr_size_t nbyte, 01286 apr_bucket_alloc_t *list); 01287 01295 APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 01296 const char *buf, 01297 apr_size_t nbyte); 01298 01313 APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 01314 apr_size_t nbyte, 01315 void (*free_func)(void *data), 01316 apr_bucket_alloc_t *list); 01326 APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf, 01327 apr_size_t nbyte, 01328 void (*free_func)(void *data)); 01329 01339 APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 01340 apr_size_t length, 01341 apr_pool_t *pool, 01342 apr_bucket_alloc_t *list); 01343 01352 APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf, 01353 apr_size_t length, 01354 apr_pool_t *pool); 01355 01356 #if APR_HAS_MMAP 01366 APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 01367 apr_off_t start, 01368 apr_size_t length, 01369 apr_bucket_alloc_t *list); 01370 01380 APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm, 01381 apr_off_t start, 01382 apr_size_t length); 01383 #endif 01384 01391 APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock, 01392 apr_bucket_alloc_t *list); 01399 APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 01400 apr_socket_t *thissock); 01401 01408 APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe, 01409 apr_bucket_alloc_t *list); 01410 01417 APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 01418 apr_file_t *thispipe); 01419 01430 APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd, 01431 apr_off_t offset, 01432 apr_size_t len, 01433 apr_pool_t *p, 01434 apr_bucket_alloc_t *list); 01435 01446 APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd, 01447 apr_off_t offset, 01448 apr_size_t len, apr_pool_t *p); 01449 01456 APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b, 01457 int enabled); 01458 01460 #ifdef __cplusplus 01461 } 01462 #endif 01463 01464 #endif /* !APR_BUCKETS_H */

Generated on Sun Nov 20 19:09:06 2005 for Apache Portable Runtime Utility Library by doxygen 1.3.8