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 as
227           well. To avoid that pass to new() a copy which you won't modify.
228
229       opt arg3: $offset ( number )
230           Optional offset inside $data. Default: 0.
231
232       opt arg4: $len ( number )
233           Optional partial length to read.
234
235           If $offset is specified, then:
236
237             length $buffer - $offset;
238
239           will be used. Otherwise the default is to use:
240
241             length $buffer;
242
243       ret: $nb ( "APR::Bucket object" )
244           a newly created bucket object
245
246       since: 2.0.00
247
248       Examples:
249
250       •   Create a new bucket using a whole string:
251
252             use APR::Bucket ();
253             my $data = "my data";
254             my $b = APR::Bucket->new($ba, $data);
255
256           now the bucket contains the string 'my data'.
257
258       •   Create a new bucket using a sub-string:
259
260             use APR::Bucket ();
261             my $data   = "my data";
262             my $offset = 3;
263             my $b = APR::Bucket->new($ba, $data, $offset);
264
265           now the bucket contains the string 'data'.
266
267       •   Create a new bucket not using the whole length and starting from an
268           offset:
269
270             use APR::Bucket ();
271             my $data   = "my data";
272             my $offset = 3;
273             my $len    = 3;
274             my $b = APR::Bucket->new($ba, $data, $offset, $len);
275
276           now the bucket contains the string 'dat'.
277
278   "read"
279       Read the data from the bucket.
280
281         $len = $b->read($buffer);
282         $len = $b->read($buffer, $block);
283
284       obj: $b ( "APR::Bucket object" )
285           The bucket to read from
286
287       arg1: $buffer ( SCALAR )
288           The buffer to fill. All previous data will be lost.
289
290       opt arg2: $block ( "APR::Const :read_type constant" )
291           optional reading mode constant.
292
293           By default the read is blocking, via "APR::Const::BLOCK_READ
294           constant".
295
296       ret: $len ( number )
297           How many bytes were actually read
298
299           $buffer gets populated with the string that is read. It will
300           contain an empty string if there was nothing to read.
301
302       since: 2.0.00
303       excpt: "APR::Error"
304
305       It's important to know that certain bucket types (e.g. file bucket),
306       may perform a split and insert extra buckets following the current one.
307       Therefore never call "$b->remove", before calling "$b->read", or you
308       may lose data.
309
310       Examples:
311
312       Blocking read:
313
314         my $len = $b->read(my $buffer);
315
316       Non-blocking read:
317
318         use APR::Const -compile 'NONBLOCK_READ';
319         my $len = $b->read(my $buffer, APR::Const::NONBLOCK_READ);
320
321   "remove"
322       Tell the bucket to remove itself from the bucket brigade it belongs to.
323
324         $bucket->remove();
325
326       obj: $bucket ( "APR::Bucket object" )
327       ret: no return value
328       since: 2.0.00
329
330       If the bucket is not attached to any bucket brigade then this operation
331       doesn't do anything.
332
333       When the bucket is removed, it's not not destroyed. Usually this is
334       done in order to move the bucket to another bucket brigade. Or to copy
335       the data way before destroying the bucket.  If the bucket wasn't moved
336       to another bucket brigade it must be destroyed.
337
338       Examples:
339
340       Assuming that $bb1 already exists and filled with buckets, move every
341       odd bucket number to $bb2 and every even to $bb3:
342
343         my $bb2 = APR::Brigade->new($c->pool, $c->bucket_alloc);
344         my $bb3 = APR::Brigade->new($c->pool, $c->bucket_alloc);
345         my $count = 0;
346         while (my $bucket = $bb->first) {
347             $count++;
348             $bucket->remove;
349             $count % 2
350                 ? $bb2->insert_tail($bucket)
351                 : $bb3->insert_tail($bucket);
352         }
353
354   "setaside"
355       Ensure the bucket's data lasts at least as long as the given pool:
356
357         my $status = $b->setaside($pool);
358
359       obj: $b ( "APR::Bucket object" )
360       arg1: $pool ( "APR::Pool object" )
361       ret: ( "APR::Const status constant" )
362           On success, "APR::Const::SUCCESS" is returned. Otherwise a failure
363           code is returned.
364
365       excpt: "APR::Error"
366           when your code deals only with mod_perl buckets, you don't have to
367           ask for the return value. If this method is called in the "VOID"
368           context, i.e.:
369
370             $b->setaside($pool);
371
372           mod_perl will do the error checking on your behalf, and if the
373           return code is not "APR::Const::SUCCESS", an "APR::Error exception"
374           will be thrown.
375
376           However if your code doesn't know which bucket types it may need to
377           setaside, you may want to check the return code and deal with any
378           errors. For example one of the possible error codes is
379           "APR::Const::ENOTIMPL". As of this writing the pipe and socket
380           buckets can't setaside(), in which case you may want to look at the
381           ap_save_brigade() implementation.
382
383       since: 2.0.00
384
385       Usually setaside is called by certain output filters, in order to
386       buffer socket writes of smaller buckets into a single write. This
387       method works on all bucket types (not only the mod_perl bucket type),
388       but as explained in the exceptions section, not all bucket types
389       implement this method.
390
391       When a mod_perl bucket is setaside, its data is detached from the
392       original perl scalar and copied into a pool bucket. That allows
393       downstream filters to deal with the data originally owned by a Perl
394       interpreter, making it possible for that interpreter to go away and do
395       other things, or be destroyed.
396
397   "type"
398       Get the type of the data in the bucket.
399
400         $type = $b->type;
401
402       obj: $b ( "APR::Bucket object" )
403       ret: $type ( "APR::BucketType object" )
404       since: 2.0.00
405
406       You need to invoke "APR::BucketType" methods to access the data.
407
408       Example:
409
410       Create a flush bucket and read its type's name:
411
412         use APR::Bucket ();
413         use APR::BucketType ();
414         my $b = APR::Bucket::flush_create($ba);
415         my $type = $b->type;
416         my $type_name =  $type->name; # FLUSH
417
418       The type name will be 'FLUSH' in this example.
419

Unsupported API

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

Copyright

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

Authors

464       The mod_perl development team and numerous contributors.
465
466
467
468perl v5.38.0                      2023-07-20         docs::api::APR::Bucket(3)