Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

APR::Brigade (3)

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

User Contributed Perl Documentation
                                    build::sparcv9::docs::api::APR::Brigade(3)



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
       "APR::Brigade" allows you to create, manipulate and delete APR bucket
       brigades.

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

   "cleanup"
       Empty out an entire bucket brigade:

         $bb->cleanup;

       obj: $bb ( "APR::Brigade object" )
           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 "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.

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

         $bb1->concat($bb2);

       obj: $bb1 ( "APR::Brigade object" )
           The brigade to concatenate to.

       arg1: $bb2 ( "APR::Brigade object" )
           The brigade to concatenate and empty afterwards.

       ret: no return value
       since: 2.0.00

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

         $bb->destroy();

       obj: $bb ( "APR::Brigade object" )
           The bucket brigade to destroy.

       ret: no return value
       excpt: "APR::Error"
       since: 2.0.00

   "is_empty"
       Test whether the bucket brigade is empty

         $ret = $bb->is_empty();

       obj: $bb ( "APR::Brigade object" )
       ret: $ret ( boolean )
       since: 2.0.00

   "first"
       Return the first bucket in a brigade

         $b_first = $bb->first;

       obj: $bb ( "APR::Brigade object" )
       ret: $b_first ( "APR::Bucket object" )
           The first bucket in the bucket brigade $bb.

           "undef" is returned if there are no buckets in $bb.

       since: 2.0.00

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

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

       obj: $bb ( "APR::Brigade object" )
       arg1: $buffer ( SCALAR )
           The buffer to fill. All previous data will be lost.

       opt arg2: $wanted ( number )
           If no argument is passed then all data will be returned. If $wanted
           is specified -- that number or less bytes will be returned.

       ret: $len ( number )
           How many bytes were actually read.

           $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
       excpt: "APR::Error"

   "insert_head"
       Insert a list of buckets at the front of a brigade

         $bb->insert_head($b);

       obj: $bb ( "APR::Brigade object" )
           Brigade to insert into

       arg1: $b ( "APR::Bucket object" )
           the bucket to insert. More buckets could be attached to that
           bucket.

       ret: no return value
       since: 2.0.00

   "insert_tail"
       Insert a list of buckets at the end of a brigade

         $bb->insert_tail($b);

       obj: $bb ( "APR::Brigade object" )
           Brigade to insert into

       arg1: $b ( "APR::Bucket object" )
           the bucket to insert. More buckets could be attached to that
           bucket.

       ret: no return value
       since: 2.0.00

   "last"
       Return the last bucket in the brigade

         $b_last = $bb->last;

       obj: $bb ( "APR::Brigade object" )
       ret: $b_last ( "APR::Bucket object" )
           The last bucket in the bucket brigade $bb.

           "undef" is returned if there are no buckets in $bb.

       since: 2.0.00

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

         $len = $bb->length;

       obj: $bb ( "APR::Brigade object" )
       ret: $len ( number )
       since: 2.0.00

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

       obj: $bb ( "APR::Brigade object or class" )
       arg1: $p ( "APR::Pool object" )
       arg2: $bucket_alloc ( "APR::BucketAlloc object" )
       ret: $nbb ( "APR::Brigade object" )
           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);

   "bucket_alloc"
       Get the bucket allocator associated with this brigade.

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

       obj: $bb ( "APR::Brigade object or class" )
       ret: $ba ( "APR::BucketAlloc object" )
       since: 2.0.00

   "next"
       Return the next bucket in a brigade

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

       obj: $bb ( "APR::Brigade object" )
       arg1: $b ( "APR::Bucket object" )
           The bucket after which the next bucket $b_next is located

       ret: $b_next ( "APR::Bucket object" )
           The next bucket after bucket $b.

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

       since: 2.0.00

   "pool"
       The pool the brigade is associated with.

         $pool = $bb->pool;

       obj: $bb ( "APR::Brigade object" )
       ret: $pool ( "APR::Pool object" )
       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.

   "prev"
       Return the previous bucket in the brigade

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

       obj: $bb ( "APR::Brigade object" )
       arg1: $b ( "APR::Bucket object" )
           The bucket located after bucket $b_prev

       ret: $b_prev ( "APR::Bucket object" )
           The bucket located before bucket $b.

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

       since: 2.0.00

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

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

       obj: $bb ( "APR::Brigade object" )
           The brigade to split

       arg1: $b ( "APR::Bucket object" )
           The first bucket of the new brigade

       ret: $bb2 ( "APR::Brigade object" )
           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"));

       $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"

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.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-----------------------------------------+
       |ATTRIBUTE TYPE |            ATTRIBUTE VALUE              |
       +---------------+-----------------------------------------+
       |Availability   | web/server/apache-24/module/apache-perl |
       +---------------+-----------------------------------------+
       |Stability      | Uncommitted                             |
       +---------------+-----------------------------------------+

NOTES
       Source code for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This software was built from source available at
       https://github.com/oracle/solaris-userland.  The original community
       source was downloaded from
       https://www.apache.org/dist/perl/mod_perl-2.0.12.tar.gz.

       Further information about this software can be found on the open source
       community website at https://perl.apache.org/.



perl v5.32.0                      2022-01-30
                                    build::sparcv9::docs::api::APR::Brigade(3)
Copyright © 1993, 2022, Oracle and/or its affiliates.  
Previous
Next