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

  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();

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

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

  $bb->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);

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();

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;

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);

since: 2.0.00

Insert a list of buckets at the front of a brigade

  $bb->insert_head($b);

ret: no return value

since: 2.0.00

Insert a list of buckets at the end of a brigade

  $bb->insert_tail($b);

ret: no return value

since: 2.0.00

Return the last bucket in the brigade

  $b_last = $bb->last;

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);

  my $ba = $bb->bucket_alloc();

since: 2.0.00

Return the next bucket in a brigade

  $b_next = $bb->next($b);

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);

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);

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

mod_perl 2.0 documentation.

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

The mod_perl development team and numerous contributors.