937a200089
This is actually a fully functional build except: * All internal shared libraries are static linked to make sure there is no interference with ports (and to reduce build time). * It does not have the python/perl/etc plugin or API support. * By default, it installs as "svnlite" rather than "svn". * If WITH_SVN added in make.conf, you get "svn". * If WITHOUT_SVNLITE is in make.conf, this is completely disabled. To be absolutely clear, this is not intended for any use other than checking out freebsd source and committing, like we once did with cvs. It should be usable for small scale local repositories that don't need the python/perl plugin architecture.
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.
|
|
|
|
|
|
-----------------------------------------------------------------------------
|