httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@locus.apache.org
Subject cvs commit: apache-2.0/src/lib/apr/buckets apr_buf.h
Date Tue, 01 Aug 2000 00:26:55 GMT
rbb         00/07/31 17:26:54

  Modified:    src/lib/apr/buckets apr_buf.h
  Log:
  Commit a bunch of docs for the bucket brigades code.  This should clear
  up where things are and where I would like to see them go.  Please, if
  there are any questions, or if I have been unclear, ask.
  
  Revision  Changes    Path
  1.20      +149 -14   apache-2.0/src/lib/apr/buckets/apr_buf.h
  
  Index: apr_buf.h
  ===================================================================
  RCS file: /home/cvs/apache-2.0/src/lib/apr/buckets/apr_buf.h,v
  retrieving revision 1.19
  retrieving revision 1.20
  diff -u -r1.19 -r1.20
  --- apr_buf.h	2000/07/31 23:23:38	1.19
  +++ apr_buf.h	2000/08/01 00:26:54	1.20
  @@ -58,6 +58,8 @@
   #include "apr_mmap.h"
   #include "apr_errno.h"
   #include "apr_private.h"
  +/* Currently we need this, but when the filtering is done, the iol's should
  + * just go away all together, and so will this.  :-)  */
   #include "../../../include/ap_iol.h"
   #ifdef HAVE_SYS_UIO_H
   #include <sys/uio.h>	/* for struct iovec */
  @@ -109,6 +111,14 @@
    * easily.
    */
   
  +/* The types of bucket brigades the code knows about.  We really don't need
  + * this enum.  All access to the bucket brigades can be done through function
  + * pointers in the bucket type.  However, when we start to do conversion
  + * routines, this enum will be a huge performance benefit, so we leave it
  + * alone.  As of this moment, only rwmem, rmem, mmap, and eos buckets have
  + * been implemented.  The rest will wait until the filtering design is
  + * decided upon, or until somebody gets around to them. 
  + */
   typedef enum {
       AP_BUCKET_rwmem,
       AP_BUCKET_rmem,
  @@ -123,6 +133,30 @@
   } ap_bucket_color_e;
   
   typedef struct ap_bucket ap_bucket;
  +/*
  + * The basic bucket type.  This is an abstraction on top of all other bucket
  + * types.  This contains the type of bucket, a pointer to the bucket, and
  + * a couple of function pointers.  Doing it this way, lets us morph buckets
  + * from one type to another relatively easily.  Just change the data pointer
  + * to point to the new bucket, and replace all of the function pointers.
  + *
  + * This also allows for a very simple interface for all features of buckets
  + * for all bucket types.   (does that make any sense at all?)
  + *
  + * The current functions are:
  + * getlen   -- get the length of the data in the bucket 
  + *                                        (likely to be replaced soon)
  + * read     -- read the data in the bucket (not garaunteed to read it all)
  + * write    -- insert data into the bucket
  + * split    -- split one bucket into two buckets
  + * free     -- destroy the bucket, freeing it's memory
  + *
  + * funtions to be added:
  + * stat     -- get all of the metadata about the bucket (lifetime, type, etc.)
  + * convert  -- change one bucket type into another bucket type.
  + *
  + * There are also pointer to the next and previus buckets in the list.
  + */
   struct ap_bucket {
       ap_bucket_color_e color;              /* what type of bucket is it */
       void *data;				  /* for use by free() */
  @@ -152,6 +186,16 @@
   };
   
   typedef struct ap_bucket_brigade ap_bucket_brigade;
  +/*
  + * This is the basic bucket brigade.  That means it is a list of buckets.
  + * It has a pool out of which the buckets and the bucket brigade are allocated.
  + * That may change though, because I am leaning towards make the buckets have
  + * the same lifetime as the data they store in most cases.  It also has a
  + * pointer to the head and tail of the bucket list.  This allows us to
  + * easily remove data from the bucket list, and to easily append data at
  + * the end.  By walking the list, it is also possible to insert in the middle
  + * of the list.
  + */
   struct ap_bucket_brigade {
       ap_pool_t *p;                       /* The pool to associate this with.
                                              I do not allocate out of the pool,
  @@ -165,6 +209,13 @@
   /*    ******  Different bucket types   *****/
   
   typedef struct ap_bucket_rmem ap_bucket_rmem;
  +/*
  + * The Read only bucket type.  This is basically for memory allocated off the
  + * stack or literal strings.  It cannot be modified, and the lifetime is
  + * defined by when it was allocated.  Most likely these should be split into
  + * two different types.  This contains a pointer to the front and end of the
  + * string so that it is possible to remove characters at either end.
  + */
   struct ap_bucket_rmem {
       size_t  alloc_len;                  /* how much was allocated */
       const void    *start;               /* Where does the actual data start
  @@ -173,6 +224,28 @@
   };
   
   typedef struct ap_bucket_rwmem ap_bucket_rwmem;
  +/*
  + * The read/write memory bucket type.  This is for data that has been 
  + * allocated out of the heap.  This bucket actually starts by allocating
  + * 4K of memory.  We do this so that the bucket has room to grow.  At the
  + * bottom of the filter stack, we are likely to have to condense the buckets
  + * to as few as possible.  By allocating a big space at the beginning, we 
  + * don't have to make as many allocations at the bottom.  If the top level
  + * handlers are written correctly, we won't have to do much copying either.
  + * Of course, for legacy handlers, we will have to condense.
  + *
  + * This bucket type has a pointer to the start of the allocation.  This will
  + * never be modified.  This is used a a reference for the free call.  It also
  + * has the length of the amount allocated.  The length could probably go
  + * away.
  + *
  + * Finally, we have a pointer to the start and end of the string currently
  + * referenced by the bucket.  The end cannot be past the original allocation
  + * pointer + the allocation length.  The start cannot be before the original
  + * allocation pointer.  We keep a pointer to the start and end so that we can
  + * easily add and remove characters at either end.  Oh, the start cannot be
  + * after the end either.
  + */
   struct ap_bucket_rwmem {
       void    *alloc_addr;                /* Where does the data start */
       size_t  alloc_len;                  /* how much was allocated */
  @@ -182,6 +255,13 @@
   };
   
   typedef struct ap_bucket_mmap ap_bucket_mmap;
  +
  +/* 
  + * The mmap bucket type.  This is basically just an allocation address and a
  + * length.  This needs to be changed to a pointer to an mmap structure that
  + * has a reference count in it, and a pointer to the beginning and end of
  + * the data the bucket is referencing.
  + */
   struct ap_bucket_mmap {
       void      *alloc_addr;   /* Where does the mmap start? */
       int       len;           /* The amount of data in the mmap that we are 
  @@ -193,13 +273,17 @@
   
   /*   ******  Bucket Brigade Functions  *****  */
   
  -/* Create a new bucket brigade */
  +/* Create a new bucket brigade.  The bucket brigade is originally empty. */
   APR_EXPORT(ap_bucket_brigade *) ap_brigade_create(ap_pool_t *p);
   
  -/* destroy an enitre bucket brigade */
  +/* destroy an enitre bucket brigade.  This includes destroying all of the
  + * buckets within the bucket brigade's bucket list. */
   APR_EXPORT(ap_status_t) ap_brigade_destroy(void *b);
   
  -/* append bucket(s) to a bucket_brigade */
  +/* append bucket(s) to a bucket_brigade.  This is the correct way to add
  + * buckets to the end of a bucket briagdes bucket list.  This will accept
  + * a list of buckets of any length.
  + */
   APR_EXPORT(void) ap_brigade_append_buckets(ap_bucket_brigade *b,
                                                     ap_bucket *e);
   
  @@ -208,45 +292,96 @@
   APR_EXPORT(void) ap_brigade_consume(ap_bucket_brigade *, int nbytes);
   
   /* create an iovec of the elements in a bucket_brigade... return number 
  -    of elements used */
  + * of elements used.  This is useful for writing to a file or to the
  + * network efficiently.
  + */
   APR_EXPORT(int) ap_brigade_to_iovec(ap_bucket_brigade *, 
                                              struct iovec *vec, int nvec);
   
   /* catenate bucket_brigade b onto bucket_brigade a, bucket_brigade b is 
  -    empty after this */
  + * empty after this.  Neither bucket brigade can be NULL, but either one of
  + * them can be emtpy when calling this function.
  + */
   APR_EXPORT(void) ap_brigade_catenate(ap_bucket_brigade *a, 
                                               ap_bucket_brigade *b);
   
  -/* Destroy the first nvec buckets. */
  +/* Destroy the first nvec buckets.  This is very much like ap_brigade_consume
  + * except instead of specifying the number of bytes to consume, it consumes
  + * a specified number of buckets.  The original purpose for this function
  + * was in ap_brigade_to_iovec.  After converting the first 16 buckets to
  + * vectors, we would destroy those 16 buckets.  My gut is that this is the
  + * wrong approach.  I plan to change this soon-ish.
  + */
   APR_EXPORT(void) ap_consume_buckets(ap_bucket_brigade *b, int nvec);
   
   /* save the buf out to the specified iol.  This can be used to flush the
  -    data to the disk, or to send it out to the network. */
  + * data to the disk, or to send it out to the network.  This is a poor 
  + * function.  It never should have been implemented.  Unfortunately, it is
  + * also required.  Once filters have been finished, the whole concept of
  + * iol's can just go away, and this function can go away with it.  The
  + * correct solution, is to have the functions that are currently calling 
  + * this just call either ap_sendv or ap_writev directly.
  + */
   APR_EXPORT(ap_status_t) ap_brigade_to_iol(ap_ssize_t *total_bytes,
                                                    ap_bucket_brigade *a, 
                                                    ap_iol *iol);
   
  +/*
  + * This function writes a bunch of strings into a bucket brigade.  How this
  + * works is a bit strange.  If there is already a rwmem bucket at the end of
  + * the list, we just add the next string to the end.  This requires a memcpy,
  + * but it is assumed that we will have to condense buckets at the bottom of
  + * the stack anyway, so we would have to do the memcpy anyway.  If there is no
  + * rwmem bucket, then we just allocate a new rmem bucket for each string.
  + * this avoids the memory allocation, and we hope that one of the intervening
  + * filters will be removing some of the data.  This may be a dubios
  + * optimization, I just don't know.
  + */
   APR_EXPORT(int) ap_brigade_vputstrs(ap_bucket_brigade *b, va_list va);
   
  +/*
  + * Both of these functions evaluate the printf and put the resulting string
  + * into a bucket at the end of the bucket brigade.  The only reason there are
  + * two of them, is that the ap_r* functions needed both.  I would love to be
  + * able to remove one, but I don't think it's feasible.
  + */
   APR_EXPORT(int) ap_brigade_printf(ap_bucket_brigade *b, const char *fmt, ...);
  -
   APR_EXPORT(int) ap_brigade_vprintf(ap_bucket_brigade *b, const char *fmt, va_list va);
   
   /*   ******  Bucket Functions  *****  */
   
  -/* destroy a bucket */
  +/* destroy a bucket, and remove it's memory.  This does not necessarily
  + * free the actual data.  For example, an mmap may have multiple buckets
  + * referenceing it (not currently implemented).  Those would only get freed
  + * when the bucket with the last reference is destroyed.  Rwmem buckets
  + * always have their data destroyed currently.
  + */
   APR_EXPORT(ap_status_t) ap_bucket_destroy(ap_bucket *e);
   
  -/* destroy an entire list of buckets */
  +/* destroy an entire list of buckets.  I am not sure how useful this is,
  + * because it basically duplicates some logic in the bucket_brigade section.
  + * I need to review where this is used and remove it if at all possible.
  + */
   APR_EXPORT(ap_status_t) ap_bucket_list_destroy(ap_bucket *e);
  -
  -/* Convert a bucket to a char * */
  -APR_EXPORT(const char *) ap_get_bucket_char_str(ap_bucket *b);
   
  -/* get the length of the data in the bucket */
  +/* get the length of the data in the bucket that is currently being
  + * referenced.  The bucket may contain more data, but if the start or end
  + * has been moved, we really don't care about it.
  + */
   APR_EXPORT(int) ap_get_bucket_len(ap_bucket *b);
   
   /****** Functions to Create Buckets of varying type ******/
  +
  +/*
  + * All of these functions are responsibly for creating a bucket and filling
  + * it out with an initial value.  Some buckets can be over-written, others
  + * can't.  What should happen, is that buckets that can't be over-written,
  + * will have NULL write functions.  That is currently broken, although it is
  + * easy to fix.  The creation routines may not allocate the space for the
  + * buckets, because we may be using a free list.  Regardless, creation
  + * routines are responsible for getting space for a bucket from someplace
  + * and inserting the initial data.
  + */
   
   /* Create a read/write memory bucket */
   APR_EXPORT(ap_bucket *) ap_bucket_rwmem_create(const void *buf,
  
  
  

Mime
View raw message