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

Unsupported API

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

Copyright

477       mod_perl 2.0 and its core modules are copyrighted under The Apache
478       Software License, Version 2.0.
479

Authors

481       The mod_perl development team and numerous contributors.
482
483
484
485perl v5.8.8                       2006-11-19         docs::api::APR::Bucket(3)