libapa...rigade(3pm)

💖 NAME 💖

APR::Brigade — the Perl API for manipulating APR Bucket Brigades. bestie, this is your girl for making, poking at, and yeeting bucket brigades 💅

---

✨ Synopsis ✨

okay so here's the whole vibe at a glance, no cap:

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 lets you create, manipulate and delete APR bucket brigades. that's it, that's the whole job, and it eats every time 🔥

---

👑 API 👑

APR::Brigade hands you these functions and/or methods, one by one, no skips:

🧹 cleanup

Empty out an entire bucket brigade:

$bb->cleanup;

• obj: $bb ( APR::Brigade object ) — the brigade to cleanup, bestie
• ret: no return value
• since: 2.0.00

this method destroys all of the buckets within the bucket brigade's bucket list. it's basically destroy(), except it does not deregister the brigade's pool() cleanup function. subtle but iconic.

generally, you should use destroy(). cleanup is the move when you've got a single brigade you wanna reuse over and over — kill all the buckets inside it, then drop fresh buckets in later. recycling era ♻️

🔗 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. read that twice, bestie, it matters 🫶

⬅️ 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. very main character energy ✨

🎀 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" — slay 💅

---

🌈 See Also 🌈

mod_perl 2.0 documentation. go read it, iykyk 📚

---

📜 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.

---

and that's the whole page, bestie!! this was perl v5.42.3, dated 2026-08-20, serving libapa...rigade(3pm) realness from the User Contributed Perl Documentation collection 💖✨🎀 go forth and manipulate those brigades, you absolute icon 👑