APR::Brigade(3pm)

1docs::api::APR::BrigadeU(s3e)r Contributed Perl Documentadtoicosn::api::APR::Brigade(3)
2
3
4

NAME

6       APR::Brigade - Perl API for manipulating APR Bucket Brigades
7

Synopsis

9         use APR::Brigade ();
10
11         $bb = APR::Brigade->new($r->pool, $c->bucket_alloc);
12         $ba = $bb->bucket_alloc();
13         $pool = $bb->pool;
14
15         $bb->insert_head($b);
16         $bb->insert_tail($b);
17
18         $b_first = $bb->first;
19         $b_last  = $bb->last;
20
21         $b_prev = $bb->prev($b_last);
22         $b_next = $bb->next($b);
23
24         $bb2 = APR::Brigade->new($r->pool, $c->bucket_alloc);
25         $bb1->concat($bb2);
26
27         $len = $bb->flatten($data);
28         $len = $bb2->flatten($data, $wanted);
29
30         $len = $bb->length;
31         $bb3 = $bb->split($b_last);
32
33         last if $bb->is_empty();
34         $bb->cleanup();
35         $bb->destroy();
36

Description

38       "APR::Brigade" allows you to create, manipulate and delete APR bucket
39       brigades.
40

API

42       "APR::Brigade" provides the following functions and/or methods:
43
44       "cleanup"
45
46       Empty out an entire bucket brigade:
47
48         $bb->cleanup;
49
50       obj: $bb ( "APR::Brigade object" )
51           The brigade to cleanup
52
53       ret: no return value
54       since: 2.0.00
55
56       This method destroys all of the buckets within the bucket brigade's
57       bucket list.  This is similar to "destroy()", except that it does not
58       deregister the brigade's "pool()" cleanup function.
59
60       Generally, you should use "destroy()".  This function can be useful in
61       situations where you have a single brigade that you wish to reuse many
62       times by destroying all of the buckets in the brigade and putting new
63       buckets into it later.
64
65       "concat"
66
67       Concatenate brigade $bb2 onto the end of brigade $bb1, leaving brigade
68       $bb2 empty:
69
70         $bb1->concat($bb2);
71
72       obj: $bb1 ( "APR::Brigade object" )
73           The brigade to concatenate to.
74
75       arg1: $bb2 ( "APR::Brigade object" )
76           The brigade to concatenate and empty afterwards.
77
78       ret: no return value
79       since: 2.0.00
80
81       "destroy"
82
83       destroy an entire bucket brigade, includes all of the buckets within
84       the bucket brigade's bucket list.
85
86         $bb->destroy();
87
88       obj: $bb ( "APR::Brigade object" )
89           The bucket brigade to destroy.
90
91       ret: no return value
92       excpt: "APR::Error"
93       since: 2.0.00
94
95       "is_empty"
96
97       Test whether the bucket brigade is empty
98
99         $ret = $bb->is_empty();
100
101       obj: $bb ( "APR::Brigade object" )
102       ret: $ret ( boolean )
103       since: 2.0.00
104
105       "first"
106
107       Return the first bucket in a brigade
108
109         $b_first = $bb->first;
110
111       obj: $bb ( "APR::Brigade object" )
112       ret: $b_first ( "APR::Bucket object" )
113           The first bucket in the bucket brigade $bb.
114
115           "undef" is returned if there are no buckets in $bb.
116
117       since: 2.0.00
118
119       "flatten"
120
121       Get the data from buckets in the bucket brigade as one string
122
123         $len = $bb->flatten($buffer);
124         $len = $bb->flatten($buffer, $wanted);
125
126       obj: $bb ( "APR::Brigade object" )
127       arg1: $buffer ( SCALAR )
128           The buffer to fill. All previous data will be lost.
129
130       opt arg2: $wanted ( number )
131           If no argument is passed then all data will be returned. If $wanted
132           is specified -- that number or less bytes will be returned.
133
134       ret: $len ( number )
135           How many bytes were actually read.
136
137           $buffer gets populated with the string that is read. It will con‐
138           tain an empty string if there was nothing to read.
139
140       since: 2.0.00
141       excpt: "APR::Error"
142
143       "insert_head"
144
145       Insert a list of buckets at the front of a brigade
146
147         $bb->insert_head($b);
148
149       obj: $bb ( "APR::Brigade object" )
150           Brigade to insert into
151
152       arg1: $b ( "APR::Bucket object" )
153           the bucket to insert. More buckets could be attached to that
154           bucket.
155
156       ret: no return value
157       since: 2.0.00
158
159       "insert_tail"
160
161       Insert a list of buckets at the end of a brigade
162
163         $bb->insert_tail($b);
164
165       obj: $bb ( "APR::Brigade object" )
166           Brigade to insert into
167
168       arg1: $b ( "APR::Bucket object" )
169           the bucket to insert. More buckets could be attached to that
170           bucket.
171
172       ret: no return value
173       since: 2.0.00
174
175       "last"
176
177       Return the last bucket in the brigade
178
179         $b_last = $bb->last;
180
181       obj: $bb ( "APR::Brigade object" )
182       ret: $b_last ( "APR::Bucket object" )
183           The last bucket in the bucket brigade $bb.
184
185           "undef" is returned if there are no buckets in $bb.
186
187       since: 2.0.00
188
189       "length"
190
191       Return the total length of the data in the brigade (not the number of
192       buckets)
193
194         $len = $bb->length;
195
196       obj: $bb ( "APR::Brigade object" )
197       ret: $len ( number )
198       since: 2.0.00
199
200       "new"
201
202         my $nbb = APR::Brigade->new($p, $bucket_alloc);
203         my $nbb =          $bb->new($p, $bucket_alloc);
204
205       obj: $bb ( "APR::Brigade object or class" )
206       arg1: $p ( "APR::Pool object" )
207       arg2: $bucket_alloc ( "APR::BucketAlloc object" )
208       ret: $nbb ( "APR::Brigade object" )
209           a newly created bucket brigade object
210
211       since: 2.0.00
212
213       Example:
214
215       Create a new bucket brigade, using the request object's pool:
216
217         use Apache2::Connection ();
218         use Apache2::RequestRec ();
219         use APR::Brigade ();
220         my $bb = APR::Brigade->new($r->pool, $r->connection->bucket_alloc);
221
222       "bucket_alloc"
223
224       Get the bucket allocator associated with this brigade.
225
226         my $ba = $bb->bucket_alloc();
227
228       obj: $bb ( "APR::Brigade object or class" )
229       ret: $ba ( "APR::BucketAlloc object" )
230       since: 2.0.00
231
232       "next"
233
234       Return the next bucket in a brigade
235
236         $b_next = $bb->next($b);
237
238       obj: $bb ( "APR::Brigade object" )
239       arg1: $b ( "APR::Bucket object" )
240           The bucket after which the next bucket $b_next is located
241
242       ret: $b_next ( "APR::Bucket object" )
243           The next bucket after bucket $b.
244
245           "undef" is returned if there is no next bucket (i.e. $b is the last
246           bucket).
247
248       since: 2.0.00
249
250       "pool"
251
252       The pool the brigade is associated with.
253
254         $pool = $bb->pool;
255
256       obj: $bb ( "APR::Brigade object" )
257       ret: $pool ( "APR::Pool object" )
258       since: 2.0.00
259
260       The data is not allocated out of the pool, but a cleanup is registered
261       with this pool.  If the brigade is destroyed by some mechanism other
262       than pool destruction, the destroying function is responsible for
263       killing the registered cleanup.
264
265       "prev"
266
267       Return the previous bucket in the brigade
268
269         $b_prev = $bb->prev($b);
270
271       obj: $bb ( "APR::Brigade object" )
272       arg1: $b ( "APR::Bucket object" )
273           The bucket located after bucket $b_prev
274
275       ret: $b_prev ( "APR::Bucket object" )
276           The bucket located before bucket $b.
277
278           "undef" is returned if there is no previous bucket (i.e. $b is the
279           first bucket).
280
281       since: 2.0.00
282
283       "split"
284
285       Split a bucket brigade into two, such that the given bucket is the
286       first in the new bucket brigade.
287
288         $bb2 = $bb->split($b);
289
290       obj: $bb ( "APR::Brigade object" )
291           The brigade to split
292
293       arg1: $b ( "APR::Bucket object" )
294           The first bucket of the new brigade
295
296       ret: $bb2 ( "APR::Brigade object" )
297           The new brigade.
298
299       since: 2.0.00
300
301       This function is useful when a filter wants to pass only the initial
302       part of a brigade to the next filter.
303
304       Example:
305
306       Create a bucket brigade with three buckets, and split it into two
307       brigade such that the second brigade will have the last two buckets.
308
309         my $bb1 = APR::Brigade->new($r->pool, $c->bucket_alloc);
310         my $ba  = $c->bucket_alloc();
311         $bb1->insert_tail(APR::Bucket->new($ba, "1"));
312         $bb1->insert_tail(APR::Bucket->new($ba, "2"));
313         $bb1->insert_tail(APR::Bucket->new($ba, "3"));
314
315       $bb1 now contains buckets "1", "2", "3". Now do the split at the second
316       bucket:
317
318         my $b = $bb1->first; # 1
319         $b = $bb1->next($b); # 2
320         my $bb2 = $bb1->split($b);
321
322       Now $bb1 contains bucket "1".  $bb2 contains buckets: "2", "3"
323

Copyright

328       mod_perl 2.0 and its core modules are copyrighted under The Apache
329       Software License, Version 2.0.
330

Authors

332       The mod_perl development team and numerous contributors.
333
334
335
336perl v5.8.8                       2006-11-19        docs::api::APR::Brigade(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors