153 lines
5.7 KiB
Plaintext
153 lines
5.7 KiB
Plaintext
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
-----------------------------------------------------------------------------
|