APR::Bucket(3pm)

1docs::api::APR::Bucket(U3s)er Contributed Perl Documentatdioocns::api::APR::Bucket(3)
2
3
4

NAME

6       APR::Bucket - Perl API for manipulating APR Buckets
7

Synopsis

9         use APR::Bucket ();
10         my $ba = $c->bucket_alloc;
11
12         $b1 = APR::Bucket->new($ba, "aaa");
13         $b2 = APR::Bucket::eos_create($ba);
14         $b3 = APR::Bucket::flush_create($ba);
15
16         $b2->is_eos;
17         $b3->is_flush;
18
19         $len = $b1->length;
20         $len = $b1->read($data);
21         $type = $b1->type;
22
23         $b1->insert_after($b2);
24         $b1->insert_before($b3);
25         $b1->remove;
26         $b1->destroy;
27
28         $b2->delete; # remove+destroy
29
30         $b4 = APR::Bucket->new($ba, "to be setaside");
31         $b4->setaside($pool);
32

Description

34       "APR::Bucket" allows you to create, manipulate and delete APR buckets.
35
36       You will probably find the various insert methods confusing, the tip is
37       to read the function right to left. The following code sample helps to
38       visualize the operations:
39
40         my $bb = APR::Brigade->new($r->pool, $ba);
41         my $d1 = APR::Bucket->new($ba, "d1");
42         my $d2 = APR::Bucket->new($ba, "d2");
43         my $f1 = APR::Bucket::flush_create($ba);
44         my $f2 = APR::Bucket::flush_create($ba);
45         my $e1 = APR::Bucket::eos_create($ba);
46                                  # head->tail
47         $bb->insert_head(  $d1); # head->d1->tail
48         $d1->insert_after( $d2); # head->d1->d2->tail
49         $d2->insert_before($f1); # head->d1->f1->d2->tail
50         $d2->insert_after( $f2); # head->d1->f1->d2->f2->tail
51         $bb->insert_tail(  $e1); # head->d1->f1->d2->f2->e1->tail
52

API

54       "APR::Bucket" provides the following functions and/or methods:
55
56   "delete"
57       Tell the bucket to remove itself from the bucket brigade it belongs to,
58       and destroy itself.
59
60         $bucket->delete();
61
62       obj: $bucket ( "APR::Bucket object" )
63       ret: no return value
64       since: 2.0.00
65
66       If the bucket is not attached to any bucket brigade then this operation
67       just destroys the bucket.
68
69       "delete" is a convenience wrapper, internally doing:
70
71         $b->remove;
72         $b->destroy;
73
74       Examples:
75
76       Assuming that $bb already exists and filled with buckets, replace the
77       existing data buckets with new buckets with upcased data;
78
79         for (my $b = $bb->first; $b; $b = $bb->next($b)) {
80            if ($b->read(my $data)) {
81                 my $nb = APR::Bucket->new($bb->bucket_alloc, uc $data);
82                 $b->insert_before($nb);
83                 $b->delete;
84                 $b = $nb;
85             }
86         }
87
88   "destroy"
89       Free the resources used by a bucket. If multiple buckets refer to the
90       same resource it is freed when the last one goes away.
91
92         $bucket->destroy();
93
94       obj: $bucket ( "APR::Bucket object" )
95       ret: no return value
96       since: 2.0.00
97
98       A bucket needs to be destroyed if it was removed from a bucket brigade,
99       to avoid memory leak.
100
101       If a bucket is linked to a bucket brigade, it needs to be removed from
102       it, before it can be destroyed.
103
104       Usually instead of calling:
105
106         $b->remove;
107         $b->destroy;
108
109       it's better to call "delete" which does exactly that.
110
111   "eos_create"
112       Create an EndOfStream bucket.
113
114         $b = APR::Bucket::eos_create($ba);
115
116       arg1: $ba ( "APR::BucketAlloc object" )
117           The freelist from which this bucket should be allocated
118
119       ret: $b ( "APR::Bucket object" )
120           The new bucket
121
122       since: 2.0.00
123
124       This bucket type indicates that there is no more data coming from down
125       the filter stack.  All filters should flush any buffered data at this
126       point.
127
128       Example:
129
130         use APR::Bucket ();
131         use Apache2::Connection ();
132         my $ba = $c->bucket_alloc;
133         my $eos_b = APR::Bucket::eos_create($ba);
134
135   "flush_create"
136       Create a flush bucket.
137
138         $b = APR::Bucket::flush_create($ba);
139
140       arg1: $ba ( "APR::BucketAlloc object" )
141           The freelist from which this bucket should be allocated
142
143       ret: $b ( "APR::Bucket object" )
144           The new bucket
145
146       since: 2.0.00
147
148       This bucket type indicates that filters should flush their data.  There
149       is no guarantee that they will flush it, but this is the best we can
150       do.
151
152   "insert_after"
153       Insert a list of buckets after a specified bucket
154
155         $after_bucket->insert_after($add_bucket);
156
157       obj: $after_bucket ( "APR::Bucket object" )
158           The bucket to insert after
159
160       arg1: $add_bucket ( "APR::Bucket object" )
161           The buckets to insert. It says buckets, since $add_bucket may have
162           more buckets attached after itself.
163
164       ret: no return value
165       since: 2.0.00
166
167   "insert_before"
168       Insert a list of buckets before a specified bucket
169
170         $before_bucket->insert_before($add_bucket);
171
172       obj: $before_bucket ( "APR::Bucket object" )
173           The bucket to insert before
174
175       arg1: $add_bucket ( "APR::Bucket object" )
176           The buckets to insert. It says buckets, since $add_bucket may have
177           more buckets attached after itself.
178
179       ret: no return value
180       since: 2.0.00
181
182   "is_eos"
183       Determine if a bucket is an EOS bucket
184
185         $ret = $bucket->is_eos();
186
187       obj: $bucket ( "APR::Bucket object" )
188       ret: $ret ( boolean )
189       since: 2.0.00
190
191   "is_flush"
192       Determine if a bucket is a FLUSH bucket
193
194         $ret = $bucket->is_flush();
195
196       obj: $bucket ( "APR::Bucket object" )
197       ret: $ret ( boolean )
198       since: 2.0.00
199
200   "length"
201       Get the length of the data in the bucket.
202
203         $len = $b->length;
204
205       obj: $b ( "APR::Bucket object" )
206       ret: $len ( integer )
207           If the length is unknown, $len value will be -1.
208
209       since: 2.0.00
210
211   "new"
212       Create a new bucket and initialize it with data:
213
214         $nb = APR::Bucket->new($ba, $data);
215         $nb =          $b->new($ba, $data);
216         $nb = APR::Bucket->new($ba, $data, $offset);
217         $nb = APR::Bucket->new($ba, $data, $offset, $len);
218
219       obj: $b ( "APR::Bucket object or class" )
220       arg1: $ba ( "APR::BucketAlloc object" )
221       arg2: $data ( string )
222           The data to initialize with.
223
224           Important: in order to avoid unnecessary data copying the variable
225           is stored in the bucket object. That means that if you modify $data
226           after passing it to "new()" you will modify the data in the bucket
227           as well. To avoid that pass to "new()" a copy which you won't
228           modify.
229
230       opt arg3: $offset ( number )
231           Optional offset inside $data. Default: 0.
232
233       opt arg4: $len ( number )
234           Optional partial length to read.
235
236           If $offset is specified, then:
237
238             length $buffer - $offset;
239
240           will be used. Otherwise the default is to use:
241
242             length $buffer;
243
244       ret: $nb ( "APR::Bucket object" )
245           a newly created bucket object
246
247       since: 2.0.00
248
249       Examples:
250
251       ·   Create a new bucket using a whole string:
252
253             use APR::Bucket ();
254             my $data = "my data";
255             my $b = APR::Bucket->new($ba, $data);
256
257           now the bucket contains the string 'my data'.
258
259       ·   Create a new bucket using a sub-string:
260
261             use APR::Bucket ();
262             my $data   = "my data";
263             my $offset = 3;
264             my $b = APR::Bucket->new($ba, $data, $offset);
265
266           now the bucket contains the string 'data'.
267
268       ·   Create a new bucket not using the whole length and starting from an
269           offset:
270
271             use APR::Bucket ();
272             my $data   = "my data";
273             my $offset = 3;
274             my $len    = 3;
275             my $b = APR::Bucket->new($ba, $data, $offset, $len);
276
277           now the bucket contains the string 'dat'.
278
279   "read"
280       Read the data from the bucket.
281
282         $len = $b->read($buffer);
283         $len = $b->read($buffer, $block);
284
285       obj: $b ( "APR::Bucket object" )
286           The bucket to read from
287
288       arg1: $buffer ( SCALAR )
289           The buffer to fill. All previous data will be lost.
290
291       opt arg2: $block ( "APR::Const :read_type constant" )
292           optional reading mode constant.
293
294           By default the read is blocking, via "APR::Const::BLOCK_READ
295           constant".
296
297       ret: $len ( number )
298           How many bytes were actually read
299
300           $buffer gets populated with the string that is read. It will
301           contain an empty string if there was nothing to read.
302
303       since: 2.0.00
304       excpt: "APR::Error"
305
306       It's important to know that certain bucket types (e.g. file bucket),
307       may perform a split and insert extra buckets following the current one.
308       Therefore never call "$b->remove", before calling "$b->read", or you
309       may lose data.
310
311       Examples:
312
313       Blocking read:
314
315         my $len = $b->read(my $buffer);
316
317       Non-blocking read:
318
319         use APR::Const -compile 'NONBLOCK_READ';
320         my $len = $b->read(my $buffer, APR::Const::NONBLOCK_READ);
321
322   "remove"
323       Tell the bucket to remove itself from the bucket brigade it belongs to.
324
325         $bucket->remove();
326
327       obj: $bucket ( "APR::Bucket object" )
328       ret: no return value
329       since: 2.0.00
330
331       If the bucket is not attached to any bucket brigade then this operation
332       doesn't do anything.
333
334       When the bucket is removed, it's not not destroyed. Usually this is
335       done in order to move the bucket to another bucket brigade. Or to copy
336       the data way before destroying the bucket.  If the bucket wasn't moved
337       to another bucket brigade it must be destroyed.
338
339       Examples:
340
341       Assuming that $bb1 already exists and filled with buckets, move every
342       odd bucket number to $bb2 and every even to $bb3:
343
344         my $bb2 = APR::Brigade->new($c->pool, $c->bucket_alloc);
345         my $bb3 = APR::Brigade->new($c->pool, $c->bucket_alloc);
346         my $count = 0;
347         while (my $bucket = $bb->first) {
348             $count++;
349             $bucket->remove;
350             $count % 2
351                 ? $bb2->insert_tail($bucket)
352                 : $bb3->insert_tail($bucket);
353         }
354
355   "setaside"
356       Ensure the bucket's data lasts at least as long as the given pool:
357
358         my $status = $b->setaside($pool);
359
360       obj: $b ( "APR::Bucket object" )
361       arg1: $pool ( "APR::Pool object" )
362       ret: ( "APR::Const status constant" )
363           On success, "APR::Const::SUCCESS" is returned. Otherwise a failure
364           code is returned.
365
366       excpt: "APR::Error"
367           when your code deals only with mod_perl buckets, you don't have to
368           ask for the return value. If this method is called in the "VOID"
369           context, i.e.:
370
371             $b->setaside($pool);
372
373           mod_perl will do the error checking on your behalf, and if the
374           return code is not "APR::Const::SUCCESS", an "APR::Error exception"
375           will be thrown.
376
377           However if your code doesn't know which bucket types it may need to
378           setaside, you may want to check the return code and deal with any
379           errors. For example one of the possible error codes is
380           "APR::Const::ENOTIMPL". As of this writing the pipe and socket
381           buckets can't "setaside()", in which case you may want to look at
382           the "ap_save_brigade()" implementation.
383
384       since: 2.0.00
385
386       Usually setaside is called by certain output filters, in order to
387       buffer socket writes of smaller buckets into a single write. This
388       method works on all bucket types (not only the mod_perl bucket type),
389       but as explained in the exceptions section, not all bucket types
390       implement this method.
391
392       When a mod_perl bucket is setaside, its data is detached from the
393       original perl scalar and copied into a pool bucket. That allows
394       downstream filters to deal with the data originally owned by a Perl
395       interpreter, making it possible for that interpreter to go away and do
396       other things, or be destroyed.
397
398   "type"
399       Get the type of the data in the bucket.
400
401         $type = $b->type;
402
403       obj: $b ( "APR::Bucket object" )
404       ret: $type ( "APR::BucketType object" )
405       since: 2.0.00
406
407       You need to invoke "APR::BucketType" methods to access the data.
408
409       Example:
410
411       Create a flush bucket and read its type's name:
412
413         use APR::Bucket ();
414         use APR::BucketType ();
415         my $b = APR::Bucket::flush_create($ba);
416         my $type = $b->type;
417         my $type_name =  $type->name; # FLUSH
418
419       The type name will be 'FLUSH' in this example.
420

Unsupported API

422       "APR::Socket" also provides auto-generated Perl interface for a few
423       other methods which aren't tested at the moment and therefore their API
424       is a subject to change. These methods will be finalized later as a need
425       arises. If you want to rely on any of the following methods please
426       contact the the mod_perl development mailing list so we can help each
427       other take the steps necessary to shift the method to an officially
428       supported API.
429
430   "data"
431         $data = $b->data;
432
433       Gives a C pointer to the address of the data in the bucket. I can't see
434       what use can be done of it in Perl.
435
436       obj: $b ( "APR::Bucket object" )
437       ret: $data ( C pointer )
438       since: subject to change
439
440   "start"
441         $start = $b->start;
442
443       It gives the offset to when a new bucket is created with a non-zero
444       offset value:
445
446         my $b = APR::Bucket->new($ba, $data, $offset, $len);
447
448       So if the offset was 3. $start will be 3 too.
449
450       I fail to see what it can be useful for to the end user (it's mainly
451       used internally).
452
453       obj: $b ( "APR::Bucket object" )
454       ret: $start ( offset number )
455       since: subject to change
456

Copyright

461       mod_perl 2.0 and its core modules are copyrighted under The Apache
462       Software License, Version 2.0.
463

Authors

465       The mod_perl development team and numerous contributors.
466
467
468
469perl v5.32.0                      2020-07-28         docs::api::APR::Bucket(3)