libapa...R::Pool(3pm)

🌸 NAME 🌸

APR::Pool — bestie, it's the Perl API for APR pools 💖 (yes this is from the User Contributed Perl Documentation, iykyk)

---

✨ SYNOPSIS ✨

Okay so here's the vibe, copy-paste core:

use APR::Pool ();

my $sp = $r->pool->new;
my $sp2 = APR::Pool->new;

# $sp3 is a subpool of $sp,
# which in turn is a subpool of $r->pool
$sp3 = $sp->new;
print '$r->pool is an ancestor of $sp3'
    if $r->pool->is_ancestor($sp3);
# but sp2 is not a sub-pool of $r->pool
print '$r->pool is not an ancestor of $sp2'
    unless $r->pool->is_ancestor($sp2);

# $sp4 and $sp are the same pool (though you can't
# compare the handle as variables)
my $sp4 = $sp3->parent_get;

# register a dummy cleanup function
# that just prints the passed args
$sp->cleanup_register(sub { print @{ $_[0] || [] } }, [1..3]);

# tag the pool
$sp->tag("My very best pool");

# clear the pool
$sp->clear();

# destroy sub pool
$sp2->destroy;

---

💖 DESCRIPTION 💖

APR::Pool hands you access to APR pools, which exist for one glorious reason: easy memory management ✨

Different pools have different life scopes, and that's the whole point — you never have to free memory yourself. It just gets freed when the pool's life comes to an end. Periodt. Like, a request pool gets born at the start of a request and destroyed at the end of it, and every single byte allocated during that request using the request pool gets freed all at once when the request wraps. Chef's kiss. 👑

Most of the time you'll just be passing various pool objects into methods that want them. And you must understand the scoping of your pools, because if you pass a long-lived server pool to a method that only needs memory for a short-scoped request, bestie… you're going to leak memory 💀. A request pool is what you want in that case. And vice versa: if you need to allocate memory for a scope longer than a single request, then a request pool is not the one, because when the request is over the memory gets freed and bad things may happen 😭.

And if you ever need to make a brand new pool? You can always do that through the new() method. Slay. 🦋

---

🎀 API 🎀

APR::Pool gives you these functions and/or methods:

🌟 cleanup_register

Register a cleanup callback to run ✨

$pool->cleanup_register($callback);
$pool->cleanup_register($callback, $arg);

• obj: $pool ( APR::Pool object ) — the pool object you're registering the cleanup callback for
• arg1: $callback ( CODE ref or sub name ) — a cleanup callback CODE reference, or just the name of the subroutine (fully qualified unless it's defined in the current package)
• opt arg2: $arg ( SCALAR ) — if you pass this optional arg, the $callback function receives it as the first and only argument when it runs
  • want to pass more than one argument? Use an ARRAY or a HASH reference 💅
• ret: literally no return value
• excpt: if a registered callback dies or throws an exception, $@ gets stringified and passed to warn(). Usually that means it lands in the error_log. But a $SIG{__WARN__} handler can catch them instead 👀

$pool->cleanup_register(sub {die "message1\n"});
$pool->cleanup_register(sub {die "message2\n"});
my @warnings;
{
    local $SIG{__WARN__}=sub {push @warnings, @_};
    $pool->destroy;       # or simply undef $pool
}

Both of the cleanups above run at the moment $pool->destroy is called. Afterwards @warnings contains message2\n and message1\n. And $pool->destroy itself does not throw an exception — any value of $@ is preserved. 🫶

• since: 2.0.00

If there's more than one callback registered (i.e. cleanup_register got called more than once on the same pool object), the last registered callback runs first (LIFO). Stack energy, not queue energy. 📚

Examples:

No arguments, using an anon sub as a cleanup callback:

$r->pool->cleanup_register(sub { warn "running cleanup" });

One or more arguments using a cleanup code reference:

$r->pool->cleanup_register(\&cleanup, $r);
$r->pool->cleanup_register(\&cleanup, [$r, $foo]);
sub cleanup {
    my @args = (@_ && ref $_[0] eq ARRAY) ? @{ +shift } : shift;
    my $r = shift @args;
    warn "cleaning up";
}

No arguments, using a function name as a cleanup callback:

$r->pool->cleanup_register('foo');

🧹 clear

Clear all the memory in the pool and run all the registered cleanups. This also destroys all sub-pools. 💥

$pool->clear();

• obj: $pool ( APR::Pool object ) — the pool to clear
• ret: no return value
• since: 2.0.00

This method differs from destroy() in that it is not freeing the previously allocated memory — instead it lets the pool re-use it for future memory allocations. Recycling queen ♻️

💀 DESTROY

DESTROY is an alias to destroy. It's there so custom APR::Pool objects get properly cleaned up when the pool object goes out of scope. If you ever want to destroy an APR::Pool object before it goes out of scope, use destroy. 🫡

• since: 2.0.00

🔥 destroy

Destroy the pool. Gone. Poof. ✨

$pool->destroy();

• obj: $pool ( APR::Pool object ) — the pool to destroy
• ret: no return value
• since: 2.0.00

This method takes a similar action to clear() and then frees all the memory.

🧬 is_ancestor

Figure out if pool a is an ancestor of pool b — family tree check, but for memory 🌳

$ret = $pool_a->is_ancestor($pool_b);

• obj: $pool_a ( APR::Pool object ) — the pool to search
• arg1: $pool_b ( APR::Pool object ) — the pool to search for
• ret: $ret ( integer ) — true if $pool_a is an ancestor of $pool_b
• since: 2.0.00

Like, for example: make a sub-pool of a given pool and check that the pool is an ancestor of that sub-pool:

use APR::Pool ();
my $pp = $r->pool;
my $sp = $pp->new();
$pp->is_ancestor($sp) or die "Don't mess with genes!";

Not messing with genes. Not on my watch. 🙈

🦋 new

Create a new sub-pool 💖

my $pool_child = $pool_parent->new;
my $pool_child = APR::Pool->new;

• obj: $pool_parent ( APR::Pool object ) — the parent pool
  • if you don't have a parent pool to create the sub-pool from, you can call this object method as a class method instead, and the sub-pool gets created from the global pool:

my $pool_child = APR::Pool->new;

• ret: $pool_child ( APR::Pool object ) — the child sub-pool
• since: 2.0.00

👑 parent_get

Get the parent pool, the original, the main character 🎀

$parent_pool = $child_pool->parent_get();

• obj: $child_pool ( APR::Pool object ) — the child pool
• ret: $parent_pool ( APR::Pool object ) — the parent pool. undef if there's no parent pool (which is the case for the top-most global pool). everybody has that one ancestor with no ancestors 🌈
• since: 2.0.00

Example: calculate how big the pool's ancestry is:

use APR::Pool ();
sub ancestry_count {
    my $child = shift;
    my $gen = 0;
    while (my $parent = $child->parent_get) {
        $gen++;
        $child = $parent;
    }
    return $gen;
}

🏷️ tag

Tag a pool (give it a name) — yes, it gets a little label, iconic behavior 💅

$pool->tag($tag);

• obj: $pool ( APR::Pool object ) — the pool to tag
• arg1: $tag ( string ) — the tag (some unique string)
• ret: no return value
• since: 2.0.00

Every pool can be tagged with a unique label. This is highkey useful when you're doing low level apr_pool C tracing (when apr is compiled with -DAPR_POOL_DEBUG). It lets you grep(1) for the tag you set, so you can single out just the traces relevant to you 🔍

Though ngl, there's no way to read the tag value back, since APR doesn't provide such an accessor method. You can name it, you just can't ask it its name. Tragic. 😭

---

🦋 Unsupported API 🦋

APR::Pool also provides an auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is subject to change 🚧. These methods will be finalized later as a need arises. If you want to rely on any of the following methods, please contact the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API. Teamwork, bestie 🫶

⚠️ cleanup_for_exec

META: Autogenerated - needs to be reviewed/completed

Preparing for exec() — close files, etc., but don't flush I/O buffers, don't wait for subprocesses, and don't free any memory. Run all of the child_cleanups, so that any unnecessary files are closed because we are about to exec a new program. No flushing, no waiting, no freeing — just closing and dipping 🏃♀️

• ret: no return value
• since: subject to change 👀

---

🌈 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. (Legends, fr fr ✨)

---

And that's a wrap, bestie — this page is from perl v5.42.3, dated 2026-08-20, and it lives at libapa...R::Pool(3pm) under User Contributed Perl Documentation. Go forth and manage that memory, no leaks, only slay 💅💖