1docs::api::APR::Pool(3)User Contributed Perl Documentatiodnocs::api::APR::Pool(3)
2
6 APR::Pool - Perl API for APR pools
7
9 use APR::Pool ();
10 my $sp = $r->pool->new;
12 my $sp2 = APR::Pool->new;
13 # $sp3 is a subpool of $sp,
15 # which in turn is a subpool of $r->pool
16 $sp3 = $sp->new;
17 print '$r->pool is an ancestor of $sp3'
18 if $r->pool->is_ancestor($sp3);
19 # but sp2 is not a sub-pool of $r->pool
20 print '$r->pool is not an ancestor of $sp2'
21 unless $r->pool->is_ancestor($sp2);
22 # $sp4 and $sp are the same pool (though you can't
24 # compare the handle as variables)
25 my $sp4 = $sp3->parent_get;
26 # register a dummy cleanup function
28 # that just prints the passed args
29 $sp->cleanup_register(sub { print @{ $_[0] ⎪⎪ [] } }, [1..3]);
30 # tag the pool
32 $sp->tag("My very best pool");
33 # clear the pool
35 $sp->clear();
36 # destroy sub pool
38 $sp2->destroy;
39
41 "APR::Pool" provides an access to APR pools, which are used for an easy
42 memory management.
43 Different pools have different life scopes and therefore one doesn't
45 need to free allocated memory explicitly, but instead it's done when
46 the pool's life is getting to an end. For example a request pool is
47 created at the beginning of a request and destroyed at the end of it,
48 and all the memory allocated during the request processing using the
49 request pool is freed at once at the end of the request.
50 Most of the time you will just pass various pool objects to the methods
52 that require them. And you must understand the scoping of the pools,
53 since if you pass a long lived server pool to a method that needs the
54 memory only for a short scoped request, you are going to leak memory. A
55 request pool should be used in such a case. And vice versa, if you need
56 to allocate some memory for a scope longer than a single request, then
57 a request pool is inappropriate, since when the request will be over,
58 the memory will be freed and bad things may happen.
59 If you need to create a new pool, you can always do that via the
61 "new()" method.
62
64 "APR::Pool" provides the following functions and/or methods:
65 "cleanup_register"
67 Register cleanup callback to run
69 $pool->cleanup_register($callback);
71 $pool->cleanup_register($callback, $arg);
72 obj: $pool ( "APR::Pool object" )
74 The pool object to register the cleanup callback for
75 arg1: $callback ( CODE ref or sub name )
77 a cleanup callback CODE reference or just a name of the subroutine
78 (fully qualified unless defined in the current package).
79 opt arg2: $arg ( SCALAR )
81 If this optional argument is passed, the $callback function will
82 receive it as the first and only argument when executed.
83 To pass more than one argument, use an ARRAY or a HASH reference
85 ret: no return value
87 excpt:
88 if the registered callback fails, it happens when the pool is
89 destroyed. The destruction is performed by Apache and it ignores
90 any failures. Even if it didn't ignore the failures, most of the
91 time the pool is destroyed when a request or connection handlers
92 are long gone. However the error is logged to error_log, so if you
93 monitor that file you will spot if there are any problems with it.
94 since: 2.0.00
96 If there is more than one callback registered (when "cleanup_register"
98 is called more than once on the same pool object), the last registered
99 callback will be executed first (LIFO).
100 Examples:
102 No arguments, using anon sub as a cleanup callback:
104 $r->pool->cleanup_register(sub { warn "running cleanup" });
106 One or more arguments using a cleanup code reference:
108 $r->pool->cleanup_register(\&cleanup, $r);
110 $r->pool->cleanup_register(\&cleanup, [$r, $foo]);
111 sub cleanup {
112 my @args = (@_ && ref $_[0] eq ARRAY) ? @{ +shift } : shift;
113 my $r = shift @args;
114 warn "cleaning up";
115 }
116 No arguments, using a function name as a cleanup callback:
118 $r->pool->cleanup_register('foo');
120 "clear"
122 Clear all memory in the pool and run all the registered cleanups. This
124 also destroys all sub-pools.
125 $pool->clear();
127 obj: $pool ( "APR::Pool object" )
129 The pool to clear
130 ret: no return value
132 since: 2.0.00
133 This method differs from "destroy()" in that it is not freeing the pre‐
135 viously allocated, but allows the pool to re-use it for the future mem‐
136 ory allocations.
137 "DESTROY"
139 "DESTROY" is an alias to "destroy". It's there so that custom
141 "APR::Pool" objects will get properly cleaned up, when the pool object
142 goes out of scope. If you ever want to destroy an "APR::Pool" object
143 before it goes out of scope, use "destroy".
144 since: 2.0.00
146 "destroy"
148 Destroy the pool.
150 $pool->destroy();
152 obj: $pool ( "APR::Pool object" )
154 The pool to destroy
155 ret: no return value
157 since: 2.0.00
158 This method takes a similar action to "clear()" and then frees all the
160 memory.
161 "is_ancestor"
163 Determine if pool a is an ancestor of pool b
165 $ret = $pool_a->is_ancestor($pool_b);
167 obj: $pool_a ( "APR::Pool object" )
169 The pool to search
170 arg1: $pool_b ( "APR::Pool object" )
172 The pool to search for
173 ret: $ret ( integer )
175 True if $pool_a is an ancestor of $pool_b.
176 since: 2.0.00
178 For example create a sub-pool of a given pool and check that the pool
180 is an ancestor of that sub-pool:
181 use APR::Pool ();
183 my $pp = $r->pool;
184 my $sp = $pp->new();
185 $pp->is_ancestor($sp) or die "Don't mess with genes!";
186 "new"
188 Create a new sub-pool
190 my $pool_child = $pool_parent->new;
192 my $pool_child = APR::Pool->new;
193 obj: $pool_parent ( "APR::Pool object" )
195 The parent pool.
196 If you don't have a parent pool to create the sub-pool from, you
198 can use this object method as a class method, in which case the
199 sub-pool will be created from the global pool:
200 my $pool_child = APR::Pool->new;
202 ret: $pool_child ( "APR::Pool object" )
204 The child sub-pool
205 since: 2.0.00
207 "parent_get"
209 Get the parent pool
211 $parent_pool = $child_pool->parent_get();
213 obj: $child_pool ( "APR::Pool object" )
215 the child pool
216 ret: $parent_pool ( "APR::Pool object" )
218 the parent pool. "undef" if there is no parent pool (which is the
219 case for the top-most global pool).
220 since: 2.0.00
222 Example: Calculate how big is the pool's ancestry:
224 use APR::Pool ();
226 sub ancestry_count {
227 my $child = shift;
228 my $gen = 0;
229 while (my $parent = $child->parent_get) {
230 $gen++;
231 $child = $parent;
232 }
233 return $gen;
234 }
235 "tag"
237 Tag a pool (give it a name)
239 $pool->tag($tag);
241 obj: $pool ( "APR::Pool object" )
243 The pool to tag
244 arg1: $tag ( string )
246 The tag (some unique string)
247 ret: no return value
249 since: 2.0.00
250 Each pool can be tagged with a unique label. This can prove useful when
252 doing low level apr_pool C tracing (when apr is compiled with
253 "-DAPR_POOL_DEBUG"). It allows you to grep(1) for the tag you have set,
254 to single out the traces relevant to you.
255 Though there is no way to get read the tag value, since APR doesn't
257 provide such an accessor method.
258
260 "APR::Pool" also provides auto-generated Perl interface for a few other
261 methods which aren't tested at the moment and therefore their API is a
262 subject to change. These methods will be finalized later as a need
263 arises. If you want to rely on any of the following methods please con‐
264 tact the the mod_perl development mailing list so we can help each
265 other take the steps necessary to shift the method to an officially
266 supported API.
267 "cleanup_for_exec"
269 META: Autogenerated - needs to be reviewed/completed
271 Preparing for exec() --- close files, etc., but *don't* flush I/O buf‐
273 fers, *don't* wait for subprocesses, and *don't* free any memory. Run
274 all of the child_cleanups, so that any unnecessary files are closed
275 because we are about to exec a new program
276 ret: no return value
278 since: subject to change
279
281 mod_perl 2.0 documentation.
282
284 mod_perl 2.0 and its core modules are copyrighted under The Apache
285 Software License, Version 2.0.
286
288 The mod_perl development team and numerous contributors.
289perl v5.8.8 2006-11-19 docs::api::APR::Pool(3)