design-guide.txt

APACHE COMMONS: serf                                    -*-indented-text-*-


TOPICS

  1. Introduction
  2. Thread Safety
  3. Pool Usage
  4. Bucket Read Functions
  5. Versioning
  6. Bucket lifetimes


-----------------------------------------------------------------------------

1. INTRODUCTION

This document details various design choices for the serf library. It
is intended to be a guide for serf developers. Of course, these design
principles, choices made, etc are a good source of information for
users of the serf library, too.


-----------------------------------------------------------------------------

2. THREAD SAFETY

The serf library should contain no mutable globals, making it is safe
to use in a multi-threaded environment.

Each "object" within the system does not need to be used from multiple
threads at a time. Thus, they require no internal mutexes, and can
disable mutexes within APR objects where applicable (e.g. pools that
are created).

The objects should not have any thread affinity (i.e. don't use
thread-local storage). This enables an application to use external
mutexes to guard entry to the serf objects, which then allows the
objects to be used from multiple threads.


-----------------------------------------------------------------------------

3. POOL USAGE

For general information on the proper use of pools, please see:

  http://cvs.apache.org/viewcvs/*checkout*/apr/docs/pool-design.html

Within serf itself, the buckets introduce a significant issue related
to pools. Since it is very possible to end up creating *many* buckets
within a transaction, and that creation could be proportional to an
incoming or outgoing data stream, a lot of care must be take to avoid
tying bucket allocations to pools. If a bucket allocated any internal
memory against a pool, and if that bucket is created an unbounded
number of times, then the pool memory could be exhausted.

Thus, buckets are allocated using a custom allocator which allows the
memory to be freed when that bucket is no longer needed. This
contrasts with pools where the "free" operation occurs over a large
set of objects, which is problematic if some are still in use.

### need more explanation of strategy/solution ...


-----------------------------------------------------------------------------

4. BUCKET READ FUNCTIONS

The bucket reading and peek functions must not block. Each read
function should return (up to) the specified amount of data. If
SERF_READ_ALL_AVAIL is passed, then the function should provide
whatever is immediately available, without blocking.

The peek function does not take a requested length because it is
non-destructive. It is not possible to "read past" any barrier with a
peek function. Thus, peek should operate like SERF_READ_ALL_AVAIL.

The return values from the read functions should follow this general
pattern:

    APR_SUCCESS    Some data was returned, and the caller can
                   immediately call the read function again to read
                   more data.

                   NOTE: when bucket behavior tracking is enabled,
                   then you must read more data from this bucket
                   before returning to the serf context loop. If a
                   bucket is not completely drained first, then it is
                   possible to deadlock (the server might not read
                   anything until you read everything it has already
                   given to you).

    APR_EAGAIN     Some data was returned, but no more is available
                   for now. The caller must "wait for a bit" or wait
                   for some event before attempting to read again
                   (basically, this simply means re-run the serf
                   context loop). Though it shouldn't be done, reading
                   again will, in all likelihood, return zero length
                   data and APR_EAGAIN again.

                   NOTE: when bucket behavior tracking is enabled,
                   then it is illegal to immediately read a bucket
                   again after it has returned APR_EAGAIN. You must
                   run the serf context loop again to (potentially)
                   fetch more data for the bucket.

    APR_EOF        Some data was returned, and this bucket has no more
                   data available and should not be read again. If you
                   happen to read it again, then it will return zero
                   length data and APR_EOF.

                   NOTE: when bucket behavior tracking is enabled,
                   then it is illegal to read this bucket ever again.

    other          An error has occurred. No data was returned. The
                   returned length is undefined.

In the above paragraphs, when it says "some data was returned", note
that this could be data of length zero.

If a length of zero is returned, then the caller should not attempt to
dereference the data pointer. It may be invalid. Note that there is no
reason to dereference that pointer, since it doesn't point to any
valid data.

Any data returned by the bucket should live as long as the bucket, or
until the next read or peek occurs.

The read_bucket function falls into a very different pattern. See its
doc string for more information.


-----------------------------------------------------------------------------

5. VERSIONING

The serf project uses the APR versioning guidelines described here:

  http://apr.apache.org/versioning.html


-----------------------------------------------------------------------------

6. BUCKET LIFETIMES

### flesh out. basically: if you hold a bucket pointer, then you own
### it. passing a bucket into another transfers ownership. use barrier
### buckets to limit destruction of a tree of buckets.


-----------------------------------------------------------------------------