"cleanup_register"¶

Register cleanup callback to run

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

obj: $pool ( "APR::Pool object" )

The pool object to register the cleanup callback for

arg1: $callback ( CODE ref or sub name )

a cleanup callback CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

opt arg2: $arg ( SCALAR )

If this optional argument is passed, the $callback function will receive it as the first and only argument when executed.

To pass more than one argument, use an ARRAY or a HASH reference

ret: no return value

excpt:

if the registered callback fails, it happens when the pool is destroyed. The destruction is performed by Apache and it ignores any failures. Even if it didn't ignore the failures, most of the time the pool is destroyed when a request or connection handlers are long gone. However the error is logged to error_log, so if you monitor that file you will spot if there are any problems with it.

since: 2.0.00

If there is more than one callback registered (when "cleanup_register" is called more than once on the same pool object), the last registered callback will be executed first (LIFO).

Examples:

No arguments, using 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 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, but allows the pool to re-use it for the future memory allocations.

"DESTROY"¶

"DESTROY" is an alias to "destroy". It's there so that custom "APR::Pool" objects will 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.

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

Determine if pool a is an ancestor of pool b

  $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

For example create 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!";

"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 use this object method as a class method, in which case the sub-pool will be 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

  $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 is no parent pool (which is the case for the top-most global pool).

since: 2.0.00

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

  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)

  $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

Each pool can be tagged with a unique label. This can prove useful when doing low level apr_pool C tracing (when apr is compiled with "-DAPR_POOL_DEBUG"). It allows you to grep(1) for the tag you have set, to single out the traces relevant to you.

Though there is no way to get read the tag value, since APR doesn't provide such an accessor method.

"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

ret: no return value

since: subject to change