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
29 # that just prints the passed args
30 $sp->cleanup_register(sub { print @{ $_[0] || [] } }, [1..3]);
31 # tag the pool
33 $sp->tag("My very best pool");
34 # clear the pool
36 $sp->clear();
37 # destroy sub pool
39 $sp2->destroy;
40
42 "APR::Pool" provides an access to APR pools, which are used for an easy
43 memory management.
44 Different pools have different life scopes and therefore one doesn't
46 need to free allocated memory explicitly, but instead it's done when
47 the pool's life is getting to an end. For example a request pool is
48 created at the beginning of a request and destroyed at the end of it,
49 and all the memory allocated during the request processing using the
50 request pool is freed at once at the end of the request.
51 Most of the time you will just pass various pool objects to the methods
53 that require them. And you must understand the scoping of the pools,
54 since if you pass a long lived server pool to a method that needs the
55 memory only for a short scoped request, you are going to leak memory. A
56 request pool should be used in such a case. And vice versa, if you need
57 to allocate some memory for a scope longer than a single request, then
58 a request pool is inappropriate, since when the request will be over,
59 the memory will be freed and bad things may happen.
60 If you need to create a new pool, you can always do that via the
62 "new()" method.
63
65 "APR::Pool" provides the following functions and/or methods:
66 "cleanup_register"
68 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
123 also destroys all sub-pools.
124 $pool->clear();
126 obj: $pool ( "APR::Pool object" )
128 The pool to clear
129 ret: no return value
131 since: 2.0.00
132 This method differs from "destroy()" in that it is not freeing the
134 previously allocated, but allows the pool to re-use it for the future
135 memory allocations.
136 "DESTROY"
138 "DESTROY" is an alias to "destroy". It's there so that custom
139 "APR::Pool" objects will get properly cleaned up, when the pool object
140 goes out of scope. If you ever want to destroy an "APR::Pool" object
141 before it goes out of scope, use "destroy".
142 since: 2.0.00
144 "destroy"
146 Destroy the pool.
147 $pool->destroy();
149 obj: $pool ( "APR::Pool object" )
151 The pool to destroy
152 ret: no return value
154 since: 2.0.00
155 This method takes a similar action to "clear()" and then frees all the
157 memory.
158 "is_ancestor"
160 Determine if pool a is an ancestor of pool b
161 $ret = $pool_a->is_ancestor($pool_b);
163 obj: $pool_a ( "APR::Pool object" )
165 The pool to search
166 arg1: $pool_b ( "APR::Pool object" )
168 The pool to search for
169 ret: $ret ( integer )
171 True if $pool_a is an ancestor of $pool_b.
172 since: 2.0.00
174 For example create a sub-pool of a given pool and check that the pool
176 is an ancestor of that sub-pool:
177 use APR::Pool ();
179 my $pp = $r->pool;
180 my $sp = $pp->new();
181 $pp->is_ancestor($sp) or die "Don't mess with genes!";
182 "new"
184 Create a new sub-pool
185 my $pool_child = $pool_parent->new;
187 my $pool_child = APR::Pool->new;
188 obj: $pool_parent ( "APR::Pool object" )
190 The parent pool.
191 If you don't have a parent pool to create the sub-pool from, you
193 can use this object method as a class method, in which case the
194 sub-pool will be created from the global pool:
195 my $pool_child = APR::Pool->new;
197 ret: $pool_child ( "APR::Pool object" )
199 The child sub-pool
200 since: 2.0.00
202 "parent_get"
204 Get the parent pool
205 $parent_pool = $child_pool->parent_get();
207 obj: $child_pool ( "APR::Pool object" )
209 the child pool
210 ret: $parent_pool ( "APR::Pool object" )
212 the parent pool. "undef" if there is no parent pool (which is the
213 case for the top-most global pool).
214 since: 2.0.00
216 Example: Calculate how big is the pool's ancestry:
218 use APR::Pool ();
220 sub ancestry_count {
221 my $child = shift;
222 my $gen = 0;
223 while (my $parent = $child->parent_get) {
224 $gen++;
225 $child = $parent;
226 }
227 return $gen;
228 }
229 "tag"
231 Tag a pool (give it a name)
232 $pool->tag($tag);
234 obj: $pool ( "APR::Pool object" )
236 The pool to tag
237 arg1: $tag ( string )
239 The tag (some unique string)
240 ret: no return value
242 since: 2.0.00
243 Each pool can be tagged with a unique label. This can prove useful when
245 doing low level apr_pool C tracing (when apr is compiled with
246 "-DAPR_POOL_DEBUG"). It allows you to grep(1) for the tag you have set,
247 to single out the traces relevant to you.
248 Though there is no way to get read the tag value, since APR doesn't
250 provide such an accessor method.
251
253 "APR::Pool" also provides auto-generated Perl interface for a few other
254 methods which aren't tested at the moment and therefore their API is a
255 subject to change. These methods will be finalized later as a need
256 arises. If you want to rely on any of the following methods please
257 contact the the mod_perl development mailing list so we can help each
258 other take the steps necessary to shift the method to an officially
259 supported API.
260 "cleanup_for_exec"
262 META: Autogenerated - needs to be reviewed/completed
263 Preparing for exec() --- close files, etc., but *don't* flush I/O
265 buffers, *don't* wait for subprocesses, and *don't* free any memory.
266 Run all of the child_cleanups, so that any unnecessary files are closed
267 because we are about to exec a new program
268 ret: no return value
270 since: subject to change
271
273 mod_perl 2.0 documentation.
274
276 mod_perl 2.0 and its core modules are copyrighted under The Apache
277 Software License, Version 2.0.
278
280 The mod_perl development team and numerous contributors.
281perl v5.10.1 2007-11-12 docs::api::APR::Pool(3)