man APR::Brigade () - Perl API for manipulating APR Bucket Brigades

NAME

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

Synopsis

  use APR::Brigade ();

  $bb = APR::Brigade->new($r->pool, $c->bucket_alloc);
  $ba = $bb->bucket_alloc();
  $pool = $bb->pool;

  $bb->insert_head($b);
  $bb->insert_tail($b);

  $b_first = $bb->first;
  $b_last  = $bb->last;

  $b_prev = $bb->prev($b_last);
  $b_next = $bb->next($b);

  $bb2 = APR::Brigade->new($r->pool, $c->bucket_alloc);
  $bb1->concat($bb2);

  $len = $bb->flatten($data);
  $len = $bb2->flatten($data, $wanted);

  $len = $bb->length;
  $bb3 = $bb->split($b_last);

  last if $bb->is_empty();
  $bb->cleanup();
  $bb->destroy();

Description

CWAPR::Brigade allows you to create, manipulate and delete APR bucket brigades.

API

CWAPR::Brigade provides the following functions and/or methods: Empty out an entire bucket brigade:

  $bb->cleanup;
The brigade to cleanup
ret: no return value
since: 2.0.00

This method destroys all of the buckets within the bucket brigade's bucket list. This is similar to CWCIdestroy()CW, except that it does not deregister the brigade's CWCIpool()CW cleanup function.

Generally, you should use CWCIdestroy()CW. This function can be useful in situations where you have a single brigade that you wish to reuse many times by destroying all of the buckets in the brigade and putting new buckets into it later. Concatenate brigade CW$bb2 onto the end of brigade CW$bb1, leaving brigade CW$bb2 empty:

  $bb1->concat($bb2);
The brigade to concatenate to. The brigade to concatenate and empty afterwards.
ret: no return value
since: 2.0.00
destroy an entire bucket brigade, includes all of the buckets within the bucket brigade's bucket list.

  $bb->destroy();
The bucket brigade to destroy.
ret: no return value
since: 2.0.00
Test whether the bucket brigade is empty

  $ret = $bb->is_empty();
since: 2.0.00
Return the first bucket in a brigade

  $b_first = $bb->first;
The first bucket in the bucket brigade CW$bb. CWundef is returned if there are no buckets in CW$bb.
since: 2.0.00
Get the data from buckets in the bucket brigade as one string

  $len = $bb->flatten($buffer);
  $len = $bb->flatten($buffer, $wanted);
The buffer to fill. All previous data will be lost. If no argument is passed then all data will be returned. If CW$wanted is specified that number or less bytes will be returned. How many bytes were actually read. CW$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.
since: 2.0.00
Insert a list of buckets at the front of a brigade

  $bb->insert_head($b);
Brigade to insert into the bucket to insert. More buckets could be attached to that bucket.
ret: no return value
since: 2.0.00
Insert a list of buckets at the end of a brigade

  $bb->insert_tail($b);
Brigade to insert into the bucket to insert. More buckets could be attached to that bucket.
ret: no return value
since: 2.0.00
Return the last bucket in the brigade

  $b_last = $bb->last;
The last bucket in the bucket brigade CW$bb. CWundef is returned if there are no buckets in CW$bb.
since: 2.0.00
Return the total length of the data in the brigade (not the number of buckets)

  $len = $bb->length;
since: 2.0.00
  my $nbb = APR::Brigade->new($p, $bucket_alloc);
  my $nbb =          $bb->new($p, $bucket_alloc);
a newly created bucket brigade object
since: 2.0.00

Example:

Create a new bucket brigade, using the request object's pool:

  use Apache2::Connection ();
  use Apache2::RequestRec ();
  use APR::Brigade ();
  my $bb = APR::Brigade->new($r->pool, $r->connection->bucket_alloc);
Get the bucket allocator associated with this brigade.

  my $ba = $bb->bucket_alloc();
since: 2.0.00
Return the next bucket in a brigade

  $b_next = $bb->next($b);
The bucket after which the next bucket CW$b_next is located The next bucket after bucket CW$b. CWundef is returned if there is no next bucket (i.e. CW$b is the last bucket).
since: 2.0.00
The pool the brigade is associated with.

  $pool = $bb->pool;
since: 2.0.00

The data is not allocated out of the pool, but a cleanup is registered with this pool. If the brigade is destroyed by some mechanism other than pool destruction, the destroying function is responsible for killing the registered cleanup. Return the previous bucket in the brigade

  $b_prev = $bb->prev($b);
The bucket located after bucket CW$b_prev The bucket located before bucket CW$b. CWundef is returned if there is no previous bucket (i.e. CW$b is the first bucket).
since: 2.0.00
Split a bucket brigade into two, such that the given bucket is the first in the new bucket brigade.

  $bb2 = $bb->split($b);
The brigade to split The first bucket of the new brigade The new brigade.
since: 2.0.00

This function is useful when a filter wants to pass only the initial part of a brigade to the next filter.

Example:

Create a bucket brigade with three buckets, and split it into two brigade such that the second brigade will have the last two buckets.

  my $bb1 = APR::Brigade->new($r->pool, $c->bucket_alloc);
  my $ba  = $c->bucket_alloc();
  $bb1->insert_tail(APR::Bucket->new($ba, "1"));
  $bb1->insert_tail(APR::Bucket->new($ba, "2"));
  $bb1->insert_tail(APR::Bucket->new($ba, "3"));

CW$bb1 now contains buckets 1, 2, 3. Now do the split at the second bucket:

  my $b = $bb1->first; # 1
  $b = $bb1->next($b); # 2
  my $bb2 = $bb1->split($b);

Now CW$bb1 contains bucket 1. CW$bb2 contains buckets: 2, 3

See Also

mod_perl 2.0 documentation.

Copyright

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

Authors

The mod_perl development team and numerous contributors.