.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "docs::api::APR::Brigade 3pm"
.TH docs::api::APR::Brigade 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
APR::Brigade \- Perl API for manipulating APR Bucket Brigades
.SH Synopsis
.IX Header "Synopsis"
.Vb 1
\&  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();
.Ve
.SH Description
.IX Header "Description"
\&\f(CW\*(C`APR::Brigade\*(C'\fR allows you to create, manipulate and delete APR bucket
brigades.
.SH API
.IX Header "API"
\&\f(CW\*(C`APR::Brigade\*(C'\fR provides the following functions and/or methods:
.ie n .SS """cleanup"""
.el .SS \f(CWcleanup\fP
.IX Subsection "cleanup"
Empty out an entire bucket brigade:
.PP
.Vb 1
\&  $bb\->cleanup;
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
The brigade to cleanup
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
This method destroys all of the buckets within the bucket brigade's
bucket list.  This is similar to \f(CWdestroy()\fR, except
that it does not deregister the brigade's \f(CWpool()\fR
cleanup function.
.PP
Generally, you should use \f(CWdestroy()\fR.  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.
.ie n .SS """concat"""
.el .SS \f(CWconcat\fP
.IX Subsection "concat"
Concatenate brigade \f(CW$bb2\fR onto the end of brigade \f(CW$bb1\fR, leaving
brigade \f(CW$bb2\fR empty:
.PP
.Vb 1
\&  $bb1\->concat($bb2);
.Ve
.ie n .IP "obj: $bb1 ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb1\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb1 ( APR::Brigade object )"
The brigade to concatenate to.
.ie n .IP "arg1: $bb2 ( ""APR::Brigade object"" )" 4
.el .IP "arg1: \f(CW$bb2\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "arg1: $bb2 ( APR::Brigade object )"
The brigade to concatenate and empty afterwards.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """destroy"""
.el .SS \f(CWdestroy\fP
.IX Subsection "destroy"
destroy an entire bucket brigade, includes all of the buckets within
the bucket brigade's bucket list.
.PP
.Vb 1
\&  $bb\->destroy();
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
The bucket brigade to destroy.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """is_empty"""
.el .SS \f(CWis_empty\fP
.IX Subsection "is_empty"
Test whether the bucket brigade is empty
.PP
.Vb 1
\&  $ret = $bb\->is_empty();
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "ret: $ret ( boolean )" 4
.el .IP "ret: \f(CW$ret\fR ( boolean )" 4
.IX Item "ret: $ret ( boolean )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """first"""
.el .SS \f(CWfirst\fP
.IX Subsection "first"
Return the first bucket in a brigade
.PP
.Vb 1
\&  $b_first = $bb\->first;
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "ret: $b_first ( ""APR::Bucket object"" )" 4
.el .IP "ret: \f(CW$b_first\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "ret: $b_first ( APR::Bucket object )"
.PD
The first bucket in the bucket brigade \f(CW$bb\fR.
.Sp
\&\f(CW\*(C`undef\*(C'\fR is returned if there are no buckets in \f(CW$bb\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """flatten"""
.el .SS \f(CWflatten\fP
.IX Subsection "flatten"
Get the data from buckets in the bucket brigade as one string
.PP
.Vb 2
\&  $len = $bb\->flatten($buffer);
\&  $len = $bb\->flatten($buffer, $wanted);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "arg1: $buffer ( SCALAR )" 4
.el .IP "arg1: \f(CW$buffer\fR ( SCALAR )" 4
.IX Item "arg1: $buffer ( SCALAR )"
.PD
The buffer to fill. All previous data will be lost.
.ie n .IP "opt arg2: $wanted ( number )" 4
.el .IP "opt arg2: \f(CW$wanted\fR ( number )" 4
.IX Item "opt arg2: $wanted ( number )"
If no argument is passed then all data will be returned. If \f(CW$wanted\fR
is specified \-\- that number or less bytes will be returned.
.ie n .IP "ret: $len ( number )" 4
.el .IP "ret: \f(CW$len\fR ( number )" 4
.IX Item "ret: $len ( number )"
How many bytes were actually read.
.Sp
\&\f(CW$buffer\fR gets populated with the string that is read. It will
contain an empty string if there was nothing to read.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD 0
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
.PD
.ie n .SS """insert_head"""
.el .SS \f(CWinsert_head\fP
.IX Subsection "insert_head"
Insert a list of buckets at the front of a brigade
.PP
.Vb 1
\&  $bb\->insert_head($b);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
Brigade to insert into
.ie n .IP "arg1: $b ( ""APR::Bucket object"" )" 4
.el .IP "arg1: \f(CW$b\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "arg1: $b ( APR::Bucket object )"
the bucket to insert. More buckets could be attached to that bucket.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """insert_tail"""
.el .SS \f(CWinsert_tail\fP
.IX Subsection "insert_tail"
Insert a list of buckets at the end of a brigade
.PP
.Vb 1
\&  $bb\->insert_tail($b);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
Brigade to insert into
.ie n .IP "arg1: $b ( ""APR::Bucket object"" )" 4
.el .IP "arg1: \f(CW$b\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "arg1: $b ( APR::Bucket object )"
the bucket to insert. More buckets could be attached to that bucket.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """last"""
.el .SS \f(CWlast\fP
.IX Subsection "last"
Return the last bucket in the brigade
.PP
.Vb 1
\&  $b_last = $bb\->last;
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "ret: $b_last ( ""APR::Bucket object"" )" 4
.el .IP "ret: \f(CW$b_last\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "ret: $b_last ( APR::Bucket object )"
.PD
The last bucket in the bucket brigade \f(CW$bb\fR.
.Sp
\&\f(CW\*(C`undef\*(C'\fR is returned if there are no buckets in \f(CW$bb\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """length"""
.el .SS \f(CWlength\fP
.IX Subsection "length"
Return the total length of the data in the brigade (not the number of
buckets)
.PP
.Vb 1
\&  $len = $bb\->length;
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "ret: $len ( number )" 4
.el .IP "ret: \f(CW$len\fR ( number )" 4
.IX Item "ret: $len ( number )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """new"""
.el .SS \f(CWnew\fP
.IX Subsection "new"
.Vb 2
\&  my $nbb = APR::Brigade\->new($p, $bucket_alloc);
\&  my $nbb =          $bb\->new($p, $bucket_alloc);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object or class"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object or class\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object or class )"
.PD 0
.ie n .IP "arg1: $p ( ""APR::Pool object"" )" 4
.el .IP "arg1: \f(CW$p\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "arg1: $p ( APR::Pool object )"
.ie n .IP "arg2: $bucket_alloc ( ""APR::BucketAlloc object"" )" 4
.el .IP "arg2: \f(CW$bucket_alloc\fR ( \f(CWAPR::BucketAlloc object\fR )" 4
.IX Item "arg2: $bucket_alloc ( APR::BucketAlloc object )"
.ie n .IP "ret: $nbb ( ""APR::Brigade object"" )" 4
.el .IP "ret: \f(CW$nbb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "ret: $nbb ( APR::Brigade object )"
.PD
a newly created bucket brigade object
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
Example:
.PP
Create a new bucket brigade, using the request object's pool:
.PP
.Vb 4
\&  use Apache2::Connection ();
\&  use Apache2::RequestRec ();
\&  use APR::Brigade ();
\&  my $bb = APR::Brigade\->new($r\->pool, $r\->connection\->bucket_alloc);
.Ve
.ie n .SS """bucket_alloc"""
.el .SS \f(CWbucket_alloc\fP
.IX Subsection "bucket_alloc"
Get the bucket allocator associated with this brigade.
.PP
.Vb 1
\&  my $ba = $bb\->bucket_alloc();
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object or class"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object or class\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object or class )"
.PD 0
.ie n .IP "ret: $ba ( ""APR::BucketAlloc object"" )" 4
.el .IP "ret: \f(CW$ba\fR ( \f(CWAPR::BucketAlloc object\fR )" 4
.IX Item "ret: $ba ( APR::BucketAlloc object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """next"""
.el .SS \f(CWnext\fP
.IX Subsection "next"
Return the next bucket in a brigade
.PP
.Vb 1
\&  $b_next = $bb\->next($b);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "arg1: $b ( ""APR::Bucket object"" )" 4
.el .IP "arg1: \f(CW$b\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "arg1: $b ( APR::Bucket object )"
.PD
The bucket after which the next bucket \f(CW$b_next\fR is located
.ie n .IP "ret: $b_next ( ""APR::Bucket object"" )" 4
.el .IP "ret: \f(CW$b_next\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "ret: $b_next ( APR::Bucket object )"
The next bucket after bucket \f(CW$b\fR.
.Sp
\&\f(CW\*(C`undef\*(C'\fR is returned if there is no next bucket (i.e. \f(CW$b\fR is the
last bucket).
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """pool"""
.el .SS \f(CWpool\fP
.IX Subsection "pool"
The pool the brigade is associated with.
.PP
.Vb 1
\&  $pool = $bb\->pool;
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "ret: $pool ( ""APR::Pool object"" )" 4
.el .IP "ret: \f(CW$pool\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "ret: $pool ( APR::Pool object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
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.
.ie n .SS """prev"""
.el .SS \f(CWprev\fP
.IX Subsection "prev"
Return the previous bucket in the brigade
.PP
.Vb 1
\&  $b_prev = $bb\->prev($b);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
.PD 0
.ie n .IP "arg1: $b ( ""APR::Bucket object"" )" 4
.el .IP "arg1: \f(CW$b\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "arg1: $b ( APR::Bucket object )"
.PD
The bucket located after bucket \f(CW$b_prev\fR
.ie n .IP "ret: $b_prev ( ""APR::Bucket object"" )" 4
.el .IP "ret: \f(CW$b_prev\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "ret: $b_prev ( APR::Bucket object )"
The bucket located before bucket \f(CW$b\fR.
.Sp
\&\f(CW\*(C`undef\*(C'\fR is returned if there is no previous bucket (i.e. \f(CW$b\fR is the
first bucket).
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """split"""
.el .SS \f(CWsplit\fP
.IX Subsection "split"
Split a bucket brigade into two, such that the given bucket is the
first in the new bucket brigade.
.PP
.Vb 1
\&  $bb2 = $bb\->split($b);
.Ve
.ie n .IP "obj: $bb ( ""APR::Brigade object"" )" 4
.el .IP "obj: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "obj: $bb ( APR::Brigade object )"
The brigade to split
.ie n .IP "arg1: $b ( ""APR::Bucket object"" )" 4
.el .IP "arg1: \f(CW$b\fR ( \f(CWAPR::Bucket object\fR )" 4
.IX Item "arg1: $b ( APR::Bucket object )"
The first bucket of the new brigade
.ie n .IP "ret: $bb2 ( ""APR::Brigade object"" )" 4
.el .IP "ret: \f(CW$bb2\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "ret: $bb2 ( APR::Brigade object )"
The new brigade.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
This function is useful when a filter wants to pass only the initial
part of a brigade to the next filter.
.PP
Example:
.PP
Create a bucket brigade with three buckets, and split it into two
brigade such that the second brigade will have the last two buckets.
.PP
.Vb 5
\&  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"));
.Ve
.PP
\&\f(CW$bb1\fR now contains buckets "1", "2", "3". Now do the split at the
second bucket:
.PP
.Vb 3
\&  my $b = $bb1\->first; # 1
\&  $b = $bb1\->next($b); # 2
\&  my $bb2 = $bb1\->split($b);
.Ve
.PP
Now \f(CW$bb1\fR contains bucket "1".  \f(CW$bb2\fR contains buckets: "2", "3"
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH Copyright
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH Authors
.IX Header "Authors"
The mod_perl development team and numerous
contributors.