=head1 NAME

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




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









=head1 Description

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






=head1 API

C<APR::Brigade> provides the following functions and/or methods:


=head2 C<cleanup>

Empty out an entire bucket brigade:

  $bb->cleanup;

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The brigade to cleanup

=item ret: no return value

=item since: 2.0.00

=back

This method destroys all of the buckets within the bucket brigade's
bucket list.  This is similar to C<L<destroy()|/C_destroy_>>, except
that it does not deregister the brigade's C<L<pool()|/C_pool_>>
cleanup function.

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









=head2 C<concat>

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

  $bb1->concat($bb2);

=over 4

=item obj: C<$bb1>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The brigade to concatenate to.

=item arg1: C<$bb2>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The brigade to concatenate and empty afterwards.

=item ret: no return value

=item since: 2.0.00

=back




=head2 C<destroy>

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

  $bb->destroy();

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The bucket brigade to destroy.

=item ret: no return value

=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>

=item since: 2.0.00

=back





=head2 C<is_empty>

Test whether the bucket brigade is empty

  $ret = $bb->is_empty();

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item ret: C<$ret> ( boolean )

=item since: 2.0.00

=back








=head2 C<first>

Return the first bucket in a brigade

  $b_first = $bb->first;

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item ret: C<$b_first>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The first bucket in the bucket brigade C<$bb>.

C<undef> is returned if there are no buckets in C<$bb>.

=item since: 2.0.00

=back







=head2 C<flatten>

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

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item arg1: C<$buffer> ( SCALAR )

The buffer to fill. All previous data will be lost.

=item opt arg2: C<$wanted> ( number )

If no argument is passed then all data will be returned. If C<$wanted>
is specified -- that number or less bytes will be returned.

=item ret: C<$len> ( number )

How many bytes were actually read.

C<$buffer> gets populated with the string that is read. It will
contain an empty string if there was nothing to read.


=item since: 2.0.00

=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>

=back







=head2 C<insert_head>

Insert a list of buckets at the front of a brigade

  $bb->insert_head($b);

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

Brigade to insert into

=item arg1: C<$b>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

the bucket to insert. More buckets could be attached to that bucket.

=item ret: no return value

=item since: 2.0.00

=back





=head2 C<insert_tail>

Insert a list of buckets at the end of a brigade

  $bb->insert_tail($b);

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

Brigade to insert into

=item arg1: C<$b>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

the bucket to insert. More buckets could be attached to that bucket.

=item ret: no return value

=item since: 2.0.00

=back







=head2 C<last>

Return the last bucket in the brigade

  $b_last = $bb->last;

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item ret: C<$b_last>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The last bucket in the bucket brigade C<$bb>.

C<undef> is returned if there are no buckets in C<$bb>.

=item since: 2.0.00

=back






=head2 C<length>

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

  $len = $bb->length;

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item ret: C<$len> ( number )

=item since: 2.0.00

=back







=head2 C<new>

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object or class|docs::2.0::api::APR::Brigade>> )

=item arg1: C<$p>
( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )

=item arg2: C<$bucket_alloc>
( C<L<APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc>> )

=item ret: C<$nbb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

a newly created bucket brigade object

=item since: 2.0.00

=back

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






=head2 C<bucket_alloc>

Get the bucket allocator associated with this brigade.

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object or class|docs::2.0::api::APR::Brigade>> )

=item ret: C<$ba>
( C<L<APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc>> )

=item since: 2.0.00

=back






=head2 C<next>

Return the next bucket in a brigade

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item arg1: C<$b>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The bucket after which the next bucket C<$b_next> is located

=item ret: C<$b_next>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The next bucket after bucket C<$b>.

C<undef> is returned if there is no next bucket (i.e. C<$b> is the
last bucket).

=item since: 2.0.00

=back







=head2 C<pool>

The pool the brigade is associated with.

  $pool = $bb->pool;

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item ret: C<$pool>
( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )

=item since: 2.0.00

=back

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.








=head2 C<prev>

Return the previous bucket in the brigade

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

=item arg1: C<$b>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The bucket located after bucket C<$b_prev>

=item ret: C<$b_prev>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The bucket located before bucket C<$b>.

C<undef> is returned if there is no previous bucket (i.e. C<$b> is the
first bucket).

=item since: 2.0.00

=back








=head2 C<split>

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

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

=over 4

=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The brigade to split

=item arg1: C<$b>
( C<L<APR::Bucket object|docs::2.0::api::APR::Bucket>> )

The first bucket of the new brigade

=item ret: C<$bb2>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )

The new brigade.

=item since: 2.0.00

=back

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

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





=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.




=head1 Copyright

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




=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut