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

/home/oden/RPM/BUILD/apr-util-1.0.0/include/apr_buckets.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00020 #ifndef APR_BUCKETS_H 00021 #define APR_BUCKETS_H 00022 00023 #if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG) 00024 #define APR_RING_DEBUG 00025 #endif 00026 00027 #include "apu.h" 00028 #include "apr_network_io.h" 00029 #include "apr_file_io.h" 00030 #include "apr_general.h" 00031 #include "apr_mmap.h" 00032 #include "apr_errno.h" 00033 #include "apr_ring.h" 00034 #include "apr.h" 00035 #if APR_HAVE_SYS_UIO_H 00036 #include <sys/uio.h> /* for struct iovec */ 00037 #endif 00038 #if APR_HAVE_STDARG_H 00039 #include <stdarg.h> 00040 #endif 00041 00042 #ifdef __cplusplus 00043 extern "C" { 00044 #endif 00045 00053 #define APR_BUCKET_BUFF_SIZE 8000 00054 00056 typedef enum { 00057 APR_BLOCK_READ, 00058 APR_NONBLOCK_READ 00059 } apr_read_type_e; 00060 00113 /* 00114 * Forward declaration of the main types. 00115 */ 00116 00118 typedef struct apr_bucket_brigade apr_bucket_brigade; 00120 typedef struct apr_bucket apr_bucket; 00122 typedef struct apr_bucket_alloc_t apr_bucket_alloc_t; 00123 00125 typedef struct apr_bucket_type_t apr_bucket_type_t; 00126 00130 struct apr_bucket_type_t { 00134 const char *name; 00139 int num_func; 00150 enum { 00152 APR_BUCKET_DATA = 0, 00154 APR_BUCKET_METADATA = 1 00155 } is_metadata; 00163 void (*destroy)(void *data); 00164 00175 apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 00176 apr_read_type_e block); 00177 00191 apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool); 00192 00202 apr_status_t (*split)(apr_bucket *e, apr_size_t point); 00203 00210 apr_status_t (*copy)(apr_bucket *e, apr_bucket **c); 00211 00212 }; 00213 00223 struct apr_bucket { 00225 APR_RING_ENTRY(apr_bucket) link; 00227 const apr_bucket_type_t *type; 00233 apr_size_t length; 00241 apr_off_t start; 00243 void *data; 00251 void (*free)(void *e); 00253 apr_bucket_alloc_t *list; 00254 }; 00255 00257 struct apr_bucket_brigade { 00263 apr_pool_t *p; 00265 /* 00266 * The apr_bucket_list structure doesn't actually need a name tag 00267 * because it has no existence independent of struct apr_bucket_brigade; 00268 * the ring macros are designed so that you can leave the name tag 00269 * argument empty in this situation but apparently the Windows compiler 00270 * doesn't like that. 00271 */ 00272 APR_RING_HEAD(apr_bucket_list, apr_bucket) list; 00274 apr_bucket_alloc_t *bucket_alloc; 00275 }; 00276 00277 00281 typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx); 00282 00283 /* 00284 * define APR_BUCKET_DEBUG if you want your brigades to be checked for 00285 * validity at every possible instant. this will slow your code down 00286 * substantially but is a very useful debugging tool. 00287 */ 00288 #ifdef APR_BUCKET_DEBUG 00289 00290 #define APR_BRIGADE_CHECK_CONSISTENCY(b) \ 00291 APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link) 00292 00293 #define APR_BUCKET_CHECK_CONSISTENCY(e) \ 00294 APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link) 00295 00296 #else 00303 #define APR_BRIGADE_CHECK_CONSISTENCY(b) 00310 #define APR_BUCKET_CHECK_CONSISTENCY(e) 00311 #endif 00312 00313 00330 #define APR_BRIGADE_SENTINEL(b) APR_RING_SENTINEL(&(b)->list, apr_bucket, link) 00331 00337 #define APR_BRIGADE_EMPTY(b) APR_RING_EMPTY(&(b)->list, apr_bucket, link) 00338 00344 #define APR_BRIGADE_FIRST(b) APR_RING_FIRST(&(b)->list) 00350 #define APR_BRIGADE_LAST(b) APR_RING_LAST(&(b)->list) 00351 00357 #define APR_BRIGADE_INSERT_HEAD(b, e) do { \ 00358 apr_bucket *ap__b = (e); \ 00359 APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link); \ 00360 APR_BRIGADE_CHECK_CONSISTENCY((b)); \ 00361 } while (0) 00362 00368 #define APR_BRIGADE_INSERT_TAIL(b, e) do { \ 00369 apr_bucket *ap__b = (e); \ 00370 APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link); \ 00371 APR_BRIGADE_CHECK_CONSISTENCY((b)); \ 00372 } while (0) 00373 00379 #define APR_BRIGADE_CONCAT(a, b) do { \ 00380 APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link); \ 00381 APR_BRIGADE_CHECK_CONSISTENCY((a)); \ 00382 } while (0) 00383 00389 #define APR_BRIGADE_PREPEND(a, b) do { \ 00390 APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link); \ 00391 APR_BRIGADE_CHECK_CONSISTENCY((a)); \ 00392 } while (0) 00393 00399 #define APR_BUCKET_INSERT_BEFORE(a, b) do { \ 00400 apr_bucket *ap__a = (a), *ap__b = (b); \ 00401 APR_RING_INSERT_BEFORE(ap__a, ap__b, link); \ 00402 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \ 00403 } while (0) 00404 00410 #define APR_BUCKET_INSERT_AFTER(a, b) do { \ 00411 apr_bucket *ap__a = (a), *ap__b = (b); \ 00412 APR_RING_INSERT_AFTER(ap__a, ap__b, link); \ 00413 APR_BUCKET_CHECK_CONSISTENCY(ap__a); \ 00414 } while (0) 00415 00421 #define APR_BUCKET_NEXT(e) APR_RING_NEXT((e), link) 00422 00427 #define APR_BUCKET_PREV(e) APR_RING_PREV((e), link) 00428 00433 #define APR_BUCKET_REMOVE(e) APR_RING_REMOVE((e), link) 00434 00439 #define APR_BUCKET_INIT(e) APR_RING_ELEM_INIT((e), link) 00440 00447 #define APR_BUCKET_IS_METADATA(e) ((e)->type->is_metadata) 00448 00454 #define APR_BUCKET_IS_FLUSH(e) ((e)->type == &apr_bucket_type_flush) 00455 00460 #define APR_BUCKET_IS_EOS(e) ((e)->type == &apr_bucket_type_eos) 00461 00466 #define APR_BUCKET_IS_FILE(e) ((e)->type == &apr_bucket_type_file) 00467 00472 #define APR_BUCKET_IS_PIPE(e) ((e)->type == &apr_bucket_type_pipe) 00473 00478 #define APR_BUCKET_IS_SOCKET(e) ((e)->type == &apr_bucket_type_socket) 00479 00484 #define APR_BUCKET_IS_HEAP(e) ((e)->type == &apr_bucket_type_heap) 00485 00490 #define APR_BUCKET_IS_TRANSIENT(e) ((e)->type == &apr_bucket_type_transient) 00491 00496 #define APR_BUCKET_IS_IMMORTAL(e) ((e)->type == &apr_bucket_type_immortal) 00497 #if APR_HAS_MMAP 00498 00503 #define APR_BUCKET_IS_MMAP(e) ((e)->type == &apr_bucket_type_mmap) 00504 #endif 00505 00510 #define APR_BUCKET_IS_POOL(e) ((e)->type == &apr_bucket_type_pool) 00511 00512 /* 00513 * General-purpose reference counting for the various bucket types. 00514 * 00515 * Any bucket type that keeps track of the resources it uses (i.e. 00516 * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to 00517 * attach a reference count to the resource so that it can be freed 00518 * when the last bucket that uses it goes away. Resource-sharing may 00519 * occur because of bucket splits or buckets that refer to globally 00520 * cached data. */ 00521 00523 typedef struct apr_bucket_refcount apr_bucket_refcount; 00530 struct apr_bucket_refcount { 00532 int refcount; 00533 }; 00534 00535 /* ***** Reference-counted bucket types ***** */ 00536 00538 typedef struct apr_bucket_heap apr_bucket_heap; 00542 struct apr_bucket_heap { 00544 apr_bucket_refcount refcount; 00548 char *base; 00550 apr_size_t alloc_len; 00552 void (*free_func)(void *data); 00553 }; 00554 00556 typedef struct apr_bucket_pool apr_bucket_pool; 00560 struct apr_bucket_pool { 00572 apr_bucket_heap heap; 00578 const char *base; 00585 apr_pool_t *pool; 00589 apr_bucket_alloc_t *list; 00590 }; 00591 00592 #if APR_HAS_MMAP 00593 00594 typedef struct apr_bucket_mmap apr_bucket_mmap; 00598 struct apr_bucket_mmap { 00600 apr_bucket_refcount refcount; 00602 apr_mmap_t *mmap; 00603 }; 00604 #endif 00605 00607 typedef struct apr_bucket_file apr_bucket_file; 00611 struct apr_bucket_file { 00613 apr_bucket_refcount refcount; 00615 apr_file_t *fd; 00618 apr_pool_t *readpool; 00619 #if APR_HAS_MMAP 00620 00622 int can_mmap; 00623 #endif /* APR_HAS_MMAP */ 00624 }; 00625 00627 typedef union apr_bucket_structs apr_bucket_structs; 00632 union apr_bucket_structs { 00633 apr_bucket b; 00634 apr_bucket_heap heap; 00635 apr_bucket_pool pool; 00636 #if APR_HAS_MMAP 00637 apr_bucket_mmap mmap; 00638 #endif 00639 apr_bucket_file file; 00640 }; 00641 00647 #define APR_BUCKET_ALLOC_SIZE APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs)) 00648 00649 /* ***** Bucket Brigade Functions ***** */ 00657 APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p, 00658 apr_bucket_alloc_t *list); 00659 00665 APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b); 00666 00678 APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data); 00679 00689 APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b, 00690 apr_bucket *e); 00691 00700 APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b, 00701 apr_off_t point, 00702 apr_bucket **after_point); 00703 00704 #if APR_NOT_DONE_YET 00711 APU_DECLARE(void) apr_brigade_consume(apr_bucket_brigade *b, 00712 apr_off_t nbytes); 00713 #endif 00714 00722 APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb, 00723 int read_all, 00724 apr_off_t *length); 00725 00733 APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb, 00734 char *c, 00735 apr_size_t *len); 00736 00744 APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 00745 char **c, 00746 apr_size_t *len, 00747 apr_pool_t *pool); 00748 00757 APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut, 00758 apr_bucket_brigade *bbIn, 00759 apr_read_type_e block, 00760 apr_off_t maxbytes); 00761 00771 APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 00772 struct iovec *vec, int *nvec); 00773 00782 APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b, 00783 apr_brigade_flush flush, 00784 void *ctx, 00785 va_list va); 00786 00796 APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b, 00797 apr_brigade_flush flush, void *ctx, 00798 const char *str, apr_size_t nbyte); 00799 00809 APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b, 00810 apr_brigade_flush flush, 00811 void *ctx, 00812 const struct iovec *vec, 00813 apr_size_t nvec); 00814 00823 APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb, 00824 apr_brigade_flush flush, void *ctx, 00825 const char *str); 00826 00835 APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b, 00836 apr_brigade_flush flush, void *ctx, 00837 const char c); 00838 00847 APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b, 00848 apr_brigade_flush flush, 00849 void *ctx, ...); 00850 00861 APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 00862 apr_brigade_flush flush, 00863 void *ctx, 00864 const char *fmt, ...) 00865 __attribute__((format(printf,4,5))); 00866 00877 APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 00878 apr_brigade_flush flush, 00879 void *ctx, 00880 const char *fmt, va_list va); 00881 00882 /* ***** Bucket freelist functions ***** */ 00896 APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p); 00897 00906 APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator); 00907 00912 APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list); 00913 00919 APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list); 00920 00925 APU_DECLARE_NONSTD(void) apr_bucket_free(void *block); 00926 00927 00928 /* ***** Bucket Functions ***** */ 00935 #define apr_bucket_destroy(e) do { \ 00936 (e)->type->destroy((e)->data); \ 00937 (e)->free(e); \ 00938 } while (0) 00939 00951 #define apr_bucket_delete(e) do { \ 00952 APR_BUCKET_REMOVE(e); \ 00953 apr_bucket_destroy(e); \ 00954 } while (0) 00955 00963 #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block) 00964 00971 #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p) 00972 00978 #define apr_bucket_split(e,point) (e)->type->split(e, point) 00979 00985 #define apr_bucket_copy(e,c) (e)->type->copy(e, c) 00986 00987 /* Bucket type handling */ 00988 00998 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data, 00999 apr_pool_t *pool); 01000 01008 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data, 01009 apr_pool_t *pool); 01010 01018 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data, 01019 apr_size_t point); 01020 01028 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e, 01029 apr_bucket **c); 01030 01040 APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data); 01041 01048 /* There is no apr_bucket_read_notimpl, because it is a required function 01049 */ 01050 01051 01052 /* All of the bucket types implemented by the core */ 01057 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush; 01063 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos; 01067 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file; 01072 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap; 01073 #if APR_HAS_MMAP 01077 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap; 01078 #endif 01084 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool; 01088 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe; 01094 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal; 01100 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient; 01104 APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket; 01105 01106 01107 /* ***** Simple buckets ***** */ 01108 01120 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b, 01121 apr_size_t point); 01122 01133 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a, 01134 apr_bucket **b); 01135 01136 01137 /* ***** Shared, reference-counted buckets ***** */ 01138 01153 APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data, 01154 apr_off_t start, 01155 apr_size_t length); 01156 01165 APU_DECLARE(int) apr_bucket_shared_destroy(void *data); 01166 01178 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b, 01179 apr_size_t point); 01180 01190 APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a, 01191 apr_bucket **b); 01192 01193 01194 /* ***** Functions to Create Buckets of varying types ***** */ 01195 /* 01196 * Each bucket type foo has two initialization functions: 01197 * apr_bucket_foo_make which sets up some already-allocated memory as a 01198 * bucket of type foo; and apr_bucket_foo_create which allocates memory 01199 * for the bucket, calls apr_bucket_make_foo, and initializes the 01200 * bucket's list pointers. The apr_bucket_foo_make functions are used 01201 * inside the bucket code to change the type of buckets in place; 01202 * other code should call apr_bucket_foo_create. All the initialization 01203 * functions change nothing if they fail. 01204 */ 01205 01212 APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list); 01213 01221 APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b); 01222 01230 APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list); 01231 01239 APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b); 01240 01248 APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 01249 apr_size_t nbyte, 01250 apr_bucket_alloc_t *list); 01251 01259 APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 01260 const char *buf, 01261 apr_size_t nbyte); 01262 01270 APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 01271 apr_size_t nbyte, 01272 apr_bucket_alloc_t *list); 01273 01281 APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 01282 const char *buf, 01283 apr_size_t nbyte); 01284 01299 APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 01300 apr_size_t nbyte, 01301 void (*free_func)(void *data), 01302 apr_bucket_alloc_t *list); 01312 APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf, 01313 apr_size_t nbyte, 01314 void (*free_func)(void *data)); 01315 01325 APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 01326 apr_size_t length, 01327 apr_pool_t *pool, 01328 apr_bucket_alloc_t *list); 01329 01338 APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf, 01339 apr_size_t length, 01340 apr_pool_t *pool); 01341 01342 #if APR_HAS_MMAP 01352 APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 01353 apr_off_t start, 01354 apr_size_t length, 01355 apr_bucket_alloc_t *list); 01356 01366 APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm, 01367 apr_off_t start, 01368 apr_size_t length); 01369 #endif 01370 01377 APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock, 01378 apr_bucket_alloc_t *list); 01385 APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 01386 apr_socket_t *thissock); 01387 01394 APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe, 01395 apr_bucket_alloc_t *list); 01396 01403 APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 01404 apr_file_t *thispipe); 01405 01416 APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd, 01417 apr_off_t offset, 01418 apr_size_t len, 01419 apr_pool_t *p, 01420 apr_bucket_alloc_t *list); 01421 01432 APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd, 01433 apr_off_t offset, 01434 apr_size_t len, apr_pool_t *p); 01435 01442 APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b, 01443 int enabled); 01444 01446 #ifdef __cplusplus 01447 } 01448 #endif 01449 01450 #endif /* !APR_BUCKETS_H */

Generated on Thu Sep 16 13:48:14 2004 for Apache Portable Runtime Utility Library by doxygen 1.3.7