include/apr_buckets.h

Go to the documentation of this file.

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef APR_BUCKETS_H
#define APR_BUCKETS_H

#if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG)
#define APR_RING_DEBUG
#endif

#include "apu.h"
#include "apr_network_io.h"
#include "apr_file_io.h"
#include "apr_general.h"
#include "apr_mmap.h"
#include "apr_errno.h"
#include "apr_ring.h"
#include "apr.h"
#if APR_HAVE_SYS_UIO_H
#include <sys/uio.h>    /* for struct iovec */
#endif
#if APR_HAVE_STDARG_H
#include <stdarg.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

#define APR_BUCKET_BUFF_SIZE 8000

typedef enum {
    APR_BLOCK_READ,   
    APR_NONBLOCK_READ 
} apr_read_type_e;

/*
 * Forward declaration of the main types.
 */

typedef struct apr_bucket_brigade apr_bucket_brigade;
typedef struct apr_bucket apr_bucket;
typedef struct apr_bucket_alloc_t apr_bucket_alloc_t;

typedef struct apr_bucket_type_t apr_bucket_type_t;

struct apr_bucket_type_t {
    const char *name;
    int num_func;
    enum {
        APR_BUCKET_DATA = 0,
        APR_BUCKET_METADATA = 1
    } is_metadata;
    void (*destroy)(void *data);

    apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 
                         apr_read_type_e block);
    
    apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool);

    apr_status_t (*split)(apr_bucket *e, apr_size_t point);

    apr_status_t (*copy)(apr_bucket *e, apr_bucket **c);

};

struct apr_bucket {
    APR_RING_ENTRY(apr_bucket) link;
    const apr_bucket_type_t *type;
    apr_size_t length;
    apr_off_t start;
    void *data; 
    void (*free)(void *e);
    apr_bucket_alloc_t *list;
};

struct apr_bucket_brigade {
    apr_pool_t *p;
    /*
     * The apr_bucket_list structure doesn't actually need a name tag
     * because it has no existence independent of struct apr_bucket_brigade;
     * the ring macros are designed so that you can leave the name tag
     * argument empty in this situation but apparently the Windows compiler
     * doesn't like that.
     */
    APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
    apr_bucket_alloc_t *bucket_alloc;
};


typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx);

/*
 * define APR_BUCKET_DEBUG if you want your brigades to be checked for
 * validity at every possible instant.  this will slow your code down
 * substantially but is a very useful debugging tool.
 */
#ifdef APR_BUCKET_DEBUG

#define APR_BRIGADE_CHECK_CONSISTENCY(b)                                \
        APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link)

#define APR_BUCKET_CHECK_CONSISTENCY(e)                                 \
        APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link)

#else

#define APR_BRIGADE_CHECK_CONSISTENCY(b)

#define APR_BUCKET_CHECK_CONSISTENCY(e)
#endif


#define APR_BRIGADE_SENTINEL(b) APR_RING_SENTINEL(&(b)->list, apr_bucket, link)

#define APR_BRIGADE_EMPTY(b)    APR_RING_EMPTY(&(b)->list, apr_bucket, link)

#define APR_BRIGADE_FIRST(b)    APR_RING_FIRST(&(b)->list)

#define APR_BRIGADE_LAST(b)     APR_RING_LAST(&(b)->list)

#define APR_BRIGADE_INSERT_HEAD(b, e) do {                              \
        apr_bucket *ap__b = (e);                                        \
        APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
    } while (0)

#define APR_BRIGADE_INSERT_TAIL(b, e) do {                              \
        apr_bucket *ap__b = (e);                                        \
        APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((b));                             \
    } while (0)

#define APR_BRIGADE_CONCAT(a, b) do {                                   \
        APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);      \
        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
    } while (0)

#define APR_BRIGADE_PREPEND(a, b) do {                                  \
        APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);     \
        APR_BRIGADE_CHECK_CONSISTENCY((a));                             \
    } while (0)

#define APR_BUCKET_INSERT_BEFORE(a, b) do {                             \
        apr_bucket *ap__a = (a), *ap__b = (b);                          \
        APR_RING_INSERT_BEFORE(ap__a, ap__b, link);                     \
        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
    } while (0)

#define APR_BUCKET_INSERT_AFTER(a, b) do {                              \
        apr_bucket *ap__a = (a), *ap__b = (b);                          \
        APR_RING_INSERT_AFTER(ap__a, ap__b, link);                      \
        APR_BUCKET_CHECK_CONSISTENCY(ap__a);                            \
    } while (0)

#define APR_BUCKET_NEXT(e)      APR_RING_NEXT((e), link)

#define APR_BUCKET_PREV(e)      APR_RING_PREV((e), link)

#define APR_BUCKET_REMOVE(e)    APR_RING_REMOVE((e), link)

#define APR_BUCKET_INIT(e)      APR_RING_ELEM_INIT((e), link)

#define APR_BUCKET_IS_METADATA(e)    ((e)->type->is_metadata)

#define APR_BUCKET_IS_FLUSH(e)       ((e)->type == &apr_bucket_type_flush)

#define APR_BUCKET_IS_EOS(e)         ((e)->type == &apr_bucket_type_eos)

#define APR_BUCKET_IS_FILE(e)        ((e)->type == &apr_bucket_type_file)

#define APR_BUCKET_IS_PIPE(e)        ((e)->type == &apr_bucket_type_pipe)

#define APR_BUCKET_IS_SOCKET(e)      ((e)->type == &apr_bucket_type_socket)

#define APR_BUCKET_IS_HEAP(e)        ((e)->type == &apr_bucket_type_heap)

#define APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)

#define APR_BUCKET_IS_IMMORTAL(e)    ((e)->type == &apr_bucket_type_immortal)
#if APR_HAS_MMAP

#define APR_BUCKET_IS_MMAP(e)        ((e)->type == &apr_bucket_type_mmap)
#endif

#define APR_BUCKET_IS_POOL(e)        ((e)->type == &apr_bucket_type_pool)

/*
 * General-purpose reference counting for the various bucket types.
 *
 * Any bucket type that keeps track of the resources it uses (i.e.
 * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
 * attach a reference count to the resource so that it can be freed
 * when the last bucket that uses it goes away. Resource-sharing may
 * occur because of bucket splits or buckets that refer to globally
 * cached data. */

typedef struct apr_bucket_refcount apr_bucket_refcount;
struct apr_bucket_refcount {
    int          refcount;
};

/*  *****  Reference-counted bucket types  *****  */

typedef struct apr_bucket_heap apr_bucket_heap;
struct apr_bucket_heap {
    apr_bucket_refcount  refcount;
    char    *base;
    apr_size_t  alloc_len;
    void (*free_func)(void *data);
};

typedef struct apr_bucket_pool apr_bucket_pool;
struct apr_bucket_pool {
    apr_bucket_heap  heap;
    const char *base;
    apr_pool_t *pool;
    apr_bucket_alloc_t *list;
};

#if APR_HAS_MMAP

typedef struct apr_bucket_mmap apr_bucket_mmap;
struct apr_bucket_mmap {
    apr_bucket_refcount  refcount;
    apr_mmap_t *mmap;
};
#endif

typedef struct apr_bucket_file apr_bucket_file;
struct apr_bucket_file {
    apr_bucket_refcount  refcount;
    apr_file_t *fd;
    apr_pool_t *readpool;
#if APR_HAS_MMAP

    int can_mmap;
#endif /* APR_HAS_MMAP */
};

typedef union apr_bucket_structs apr_bucket_structs;
union apr_bucket_structs {
    apr_bucket      b;      
    apr_bucket_heap heap;   
    apr_bucket_pool pool;   
#if APR_HAS_MMAP
    apr_bucket_mmap mmap;   
#endif
    apr_bucket_file file;   
};

#define APR_BUCKET_ALLOC_SIZE  APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))

/*  *****  Bucket Brigade Functions  *****  */
APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p,
                                                     apr_bucket_alloc_t *list);

APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b);

APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data);

APU_DECLARE(apr_bucket_brigade *) apr_brigade_split_ex(apr_bucket_brigade *b,
                                                       apr_bucket *e,
                                                       apr_bucket_brigade *a);

APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b,
                                                    apr_bucket *e);

APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b,
                                                apr_off_t point,
                                                apr_bucket **after_point);

APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
                                             int read_all,
                                             apr_off_t *length);

APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb,
                                              char *c,
                                              apr_size_t *len);

APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 
                                               char **c,
                                               apr_size_t *len,
                                               apr_pool_t *pool);

APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut,
                                                 apr_bucket_brigade *bbIn,
                                                 apr_read_type_e block,
                                                 apr_off_t maxbytes);

APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 
                                               struct iovec *vec, int *nvec);

APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b,
                                               apr_brigade_flush flush,
                                               void *ctx,
                                               va_list va);

APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b,
                                            apr_brigade_flush flush, void *ctx,
                                            const char *str, apr_size_t nbyte);

APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b,
                                             apr_brigade_flush flush,
                                             void *ctx,
                                             const struct iovec *vec,
                                             apr_size_t nvec);

APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb,
                                           apr_brigade_flush flush, void *ctx,
                                           const char *str);

APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b,
                                           apr_brigade_flush flush, void *ctx,
                                           const char c);

APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b,
                                                     apr_brigade_flush flush,
                                                     void *ctx, ...);

APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 
                                                    apr_brigade_flush flush,
                                                    void *ctx,
                                                    const char *fmt, ...)
        __attribute__((format(printf,4,5)));

APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 
                                              apr_brigade_flush flush,
                                              void *ctx,
                                              const char *fmt, va_list va);

APU_DECLARE(apr_bucket *) apr_brigade_insert_file(apr_bucket_brigade *bb,
                                                  apr_file_t *f,
                                                  apr_off_t start,
                                                  apr_off_t len,
                                                  apr_pool_t *p);



/*  *****  Bucket freelist functions *****  */
APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p);

APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator);

APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list);

APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list);

APU_DECLARE_NONSTD(void) apr_bucket_free(void *block);


/*  *****  Bucket Functions  *****  */
#define apr_bucket_destroy(e) do {                                      \
        (e)->type->destroy((e)->data);                                  \
        (e)->free(e);                                                   \
    } while (0)

#define apr_bucket_delete(e) do {                                       \
        APR_BUCKET_REMOVE(e);                                           \
        apr_bucket_destroy(e);                                          \
    } while (0)

#define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)

#define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)

#define apr_bucket_split(e,point) (e)->type->split(e, point)

#define apr_bucket_copy(e,c) (e)->type->copy(e, c)

/* Bucket type handling */

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data,
                                                          apr_pool_t *pool);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data,
                                                             apr_pool_t *pool);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data,
                                                          apr_size_t point);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e,
                                                         apr_bucket **c);

APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data);

/* There is no apr_bucket_read_notimpl, because it is a required function
 */


/* All of the bucket types implemented by the core */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
#if APR_HAS_MMAP

APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
#endif

APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;


/*  *****  Simple buckets  *****  */

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
                                                         apr_size_t point);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
                                                        apr_bucket **b);


/*  *****  Shared, reference-counted buckets  *****  */

APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
                                                 apr_off_t start, 
                                                 apr_size_t length);

APU_DECLARE(int) apr_bucket_shared_destroy(void *data);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
                                                         apr_size_t point);

APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
                                                        apr_bucket **b);


/*  *****  Functions to Create Buckets of varying types  *****  */
/*
 * Each bucket type foo has two initialization functions:
 * apr_bucket_foo_make which sets up some already-allocated memory as a
 * bucket of type foo; and apr_bucket_foo_create which allocates memory
 * for the bucket, calls apr_bucket_make_foo, and initializes the
 * bucket's list pointers. The apr_bucket_foo_make functions are used
 * inside the bucket code to change the type of buckets in place;
 * other code should call apr_bucket_foo_create. All the initialization
 * functions change nothing if they fail.
 */

APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);

APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);

APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 
                                                     apr_size_t nbyte,
                                                     apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 
                                                   const char *buf, 
                                                   apr_size_t nbyte);

APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 
                                                      apr_size_t nbyte,
                                                      apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 
                                                    const char *buf,
                                                    apr_size_t nbyte);

APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 
                                                 apr_size_t nbyte,
                                                 void (*free_func)(void *data),
                                                 apr_bucket_alloc_t *list);
APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf,
                                               apr_size_t nbyte,
                                               void (*free_func)(void *data));

APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 
                                                 apr_size_t length,
                                                 apr_pool_t *pool,
                                                 apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf,
                                               apr_size_t length, 
                                               apr_pool_t *pool);

#if APR_HAS_MMAP

APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 
                                                 apr_off_t start,
                                                 apr_size_t length,
                                                 apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm,
                                               apr_off_t start, 
                                               apr_size_t length);
#endif

APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock,
                                                   apr_bucket_alloc_t *list);
APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 
                                                 apr_socket_t *thissock);

APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe,
                                                 apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 
                                               apr_file_t *thispipe);

APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd,
                                                 apr_off_t offset,
                                                 apr_size_t len, 
                                                 apr_pool_t *p,
                                                 apr_bucket_alloc_t *list);

APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
                                               apr_off_t offset,
                                               apr_size_t len, apr_pool_t *p);

APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b,
                                                      int enabled);

#ifdef __cplusplus
}
#endif

#endif /* !APR_BUCKETS_H */