1
by Noritada Kobayashi
Import upstream version 0.1.0 |
1 |
APACHE COMMONS: serf -*-indented-text-*- |
2 |
||
3 |
||
4 |
TOPICS |
|
5 |
||
6 |
1. Introduction |
|
7 |
2. Thread Safety |
|
8 |
3. Pool Usage |
|
9 |
4. Bucket Read Functions |
|
10 |
5. Versioning |
|
11 |
6. Bucket lifetimes |
|
12 |
||
13 |
||
14 |
----------------------------------------------------------------------------- |
|
15 |
||
16 |
1. INTRODUCTION |
|
17 |
||
18 |
This document details various design choices for the serf library. It |
|
19 |
is intended to be a guide for serf developers. Of course, these design |
|
20 |
principles, choices made, etc are a good source of information for |
|
21 |
users of the serf library, too. |
|
22 |
||
23 |
||
24 |
----------------------------------------------------------------------------- |
|
25 |
||
26 |
2. THREAD SAFETY |
|
27 |
||
28 |
The serf library should contain no mutable globals, making it is safe |
|
29 |
to use in a multi-threaded environment. |
|
30 |
||
31 |
Each "object" within the system does not need to be used from multiple |
|
32 |
threads at a time. Thus, they require no internal mutexes, and can |
|
33 |
disable mutexes within APR objects where applicable (e.g. pools that |
|
34 |
are created). |
|
35 |
||
36 |
The objects should not have any thread affinity (i.e. don't use |
|
37 |
thread-local storage). This enables an application to use external |
|
38 |
mutexes to guard entry to the serf objects, which then allows the |
|
39 |
objects to be used from multiple threads. |
|
40 |
||
41 |
||
42 |
----------------------------------------------------------------------------- |
|
43 |
||
44 |
3. POOL USAGE |
|
45 |
||
46 |
For general information on the proper use of pools, please see: |
|
47 |
||
48 |
http://cvs.apache.org/viewcvs/*checkout*/apr/docs/pool-design.html |
|
49 |
||
50 |
Within serf itself, the buckets introduce a significant issue related |
|
51 |
to pools. Since it is very possible to end up creating *many* buckets |
|
52 |
within a transaction, and that creation could be proportional to an |
|
53 |
incoming or outgoing data stream, a lot of care must be take to avoid |
|
54 |
tying bucket allocations to pools. If a bucket allocated any internal |
|
55 |
memory against a pool, and if that bucket is created an unbounded |
|
56 |
number of times, then the pool memory could be exhausted. |
|
57 |
||
58 |
Thus, buckets are allocated using a custom allocator which allows the |
|
59 |
memory to be freed when that bucket is no longer needed. This |
|
60 |
contrasts with pools where the "free" operation occurs over a large |
|
61 |
set of objects, which is problematic if some are still in use. |
|
62 |
||
63 |
### need more explanation of strategy/solution ... |
|
64 |
||
65 |
||
66 |
----------------------------------------------------------------------------- |
|
67 |
||
68 |
4. BUCKET READ FUNCTIONS |
|
69 |
||
70 |
The bucket reading and peek functions must not block. Each read |
|
71 |
function should return (up to) the specified amount of data. If |
|
72 |
SERF_READ_ALL_AVAIL is passed, then the function should provide |
|
73 |
whatever is immediately available, without blocking. |
|
74 |
||
75 |
The peek function does not take a requested length because it is |
|
76 |
non-destructive. It is not possible to "read past" any barrier with a |
|
77 |
peek function. Thus, peek should operate like SERF_READ_ALL_AVAIL. |
|
78 |
||
79 |
The return values from the read functions should follow this general |
|
80 |
pattern: |
|
81 |
||
82 |
APR_SUCCESS Some data was returned, and the caller can |
|
83 |
immediately call the read function again to read |
|
84 |
more data. |
|
85 |
||
86 |
NOTE: when bucket behavior tracking is enabled, |
|
87 |
then you must read more data from this bucket |
|
88 |
before returning to the serf context loop. If a |
|
89 |
bucket is not completely drained first, then it is |
|
90 |
possible to deadlock (the server might not read |
|
91 |
anything until you read everything it has already |
|
92 |
given to you). |
|
93 |
||
94 |
APR_EAGAIN Some data was returned, but no more is available |
|
95 |
for now. The caller must "wait for a bit" or wait |
|
96 |
for some event before attempting to read again |
|
97 |
(basically, this simply means re-run the serf |
|
98 |
context loop). Though it shouldn't be done, reading |
|
99 |
again will, in all likelihood, return zero length |
|
100 |
data and APR_EAGAIN again. |
|
101 |
||
102 |
NOTE: when bucket behavior tracking is enabled, |
|
103 |
then it is illegal to immediately read a bucket |
|
104 |
again after it has returned APR_EAGAIN. You must |
|
105 |
run the serf context loop again to (potentially) |
|
106 |
fetch more data for the bucket. |
|
107 |
||
108 |
APR_EOF Some data was returned, and this bucket has no more |
|
109 |
data available and should not be read again. If you |
|
110 |
happen to read it again, then it will return zero |
|
111 |
length data and APR_EOF. |
|
112 |
||
113 |
NOTE: when bucket behavior tracking is enabled, |
|
114 |
then it is illegal to read this bucket ever again. |
|
115 |
||
116 |
other An error has occurred. No data was returned. The |
|
117 |
returned length is undefined. |
|
118 |
||
119 |
In the above paragraphs, when it says "some data was returned", note |
|
120 |
that this could be data of length zero. |
|
121 |
||
122 |
If a length of zero is returned, then the caller should not attempt to |
|
123 |
dereference the data pointer. It may be invalid. Note that there is no |
|
124 |
reason to dereference that pointer, since it doesn't point to any |
|
125 |
valid data. |
|
126 |
||
127 |
Any data returned by the bucket should live as long as the bucket, or |
|
128 |
until the next read or peek occurs. |
|
129 |
||
130 |
The read_bucket function falls into a very different pattern. See its |
|
131 |
doc string for more information. |
|
132 |
||
133 |
||
134 |
----------------------------------------------------------------------------- |
|
135 |
||
136 |
5. VERSIONING |
|
137 |
||
138 |
The serf project uses the APR versioning guidelines described here: |
|
139 |
||
140 |
http://apr.apache.org/versioning.html |
|
141 |
||
142 |
||
143 |
----------------------------------------------------------------------------- |
|
144 |
||
145 |
6. BUCKET LIFETIMES |
|
146 |
||
147 |
### flesh out. basically: if you hold a bucket pointer, then you own |
|
148 |
### it. passing a bucket into another transfers ownership. use barrier |
|
149 |
### buckets to limit destruction of a tree of buckets. |
|
150 |
||
151 |
||
152 |
----------------------------------------------------------------------------- |