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

Copyright

312       mod_perl 2.0 and its core modules are copyrighted under The Apache
313       Software License, Version 2.0.
314

Authors

316       The mod_perl development team and numerous contributors.
317
318
319
320perl v5.34.0                      2022-02-02        docs::api::APR::Brigade(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors