mod_perl logo perl icon
previous page: APR::Base64 - Perl API for APR base64 encoding/decoding functionalitypage up: mod_perl 2.0 APInext page: APR::Bucket - Perl API for manipulating APR Buckets

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






Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt
Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes
mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford


Table of Contents

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


TOP

Description

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



TOP

API

APR::Brigade provides the following functions and/or methods:



TOP

cleanup

Empty out an entire bucket brigade:

  $bb->cleanup;

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

Generally, you should use destroy(). 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.



TOP

concat

Concatenate brigade $bb2 onto the end of brigade $bb1, leaving brigade $bb2 empty:

  $bb1->concat($bb2);


TOP

destroy

destroy an entire bucket brigade, includes all of the buckets within the bucket brigade's bucket list.

  $bb->destroy();


TOP

is_empty

Test whether the bucket brigade is empty

  $ret = $bb->is_empty();


TOP

first

Return the first bucket in a brigade

  $b_first = $bb->first;


TOP

flatten

Get the data from buckets in the bucket brigade as one string

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


TOP

insert_head

Insert a list of buckets at the front of a brigade

  $bb->insert_head($b);


TOP

insert_tail

Insert a list of buckets at the end of a brigade

  $bb->insert_tail($b);


TOP

last

Return the last bucket in the brigade

  $b_last = $bb->last;


TOP

length

Return the total length of the data in the brigade (not the number of buckets)

  $len = $bb->length;


TOP

new

  my $nbb = APR::Brigade->new($p, $bucket_alloc);
  my $nbb =          $bb->new($p, $bucket_alloc);

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


TOP

bucket_alloc

Get the bucket allocator associated with this brigade.

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


TOP

next

Return the next bucket in a brigade

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


TOP

pool

The pool the brigade is associated with.

  $pool = $bb->pool;

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.



TOP

prev

Return the previous bucket in the brigade

  $b_prev = $bb->prev($b);


TOP

split

Split a bucket brigade into two, such that the given bucket is the first in the new bucket brigade.

  $bb2 = $bb->split($b);

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

$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 $bb1 contains bucket "1". $bb2 contains buckets: "2", "3"



TOP

See Also

mod_perl 2.0 documentation.



TOP

Copyright

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



TOP

Authors

The mod_perl development team and numerous contributors.






TOP
previous page: APR::Base64 - Perl API for APR base64 encoding/decoding functionalitypage up: mod_perl 2.0 APInext page: APR::Bucket - Perl API for manipulating APR Buckets