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 new()
62 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 a registered callback dies or throws an exception $@ is
89 stringified and passed to warn(). Usually, this results in printing
90 it to the error_log. However, a $SIG{__WARN__} handler can be used
91 to catch them.
92 $pool->cleanup_register(sub {die "message1\n"});
94 $pool->cleanup_register(sub {die "message2\n"});
95 my @warnings;
96 {
97 local $SIG{__WARN__}=sub {push @warnings, @_};
98 $pool->destroy; # or simply undef $pool
99 }
100 Both of the cleanups above are executed at the time
102 "$pool->destroy" is called. @warnings contains "message2\n" and
103 "message1\n" afterwards. "$pool->destroy" itself does not throw an
104 exception. Any value of $@ is preserved.
105 since: 2.0.00
107 If there is more than one callback registered (when "cleanup_register"
109 is called more than once on the same pool object), the last registered
110 callback will be executed first (LIFO).
111 Examples:
113 No arguments, using anon sub as a cleanup callback:
115 $r->pool->cleanup_register(sub { warn "running cleanup" });
117 One or more arguments using a cleanup code reference:
119 $r->pool->cleanup_register(\&cleanup, $r);
121 $r->pool->cleanup_register(\&cleanup, [$r, $foo]);
122 sub cleanup {
123 my @args = (@_ && ref $_[0] eq ARRAY) ? @{ +shift } : shift;
124 my $r = shift @args;
125 warn "cleaning up";
126 }
127 No arguments, using a function name as a cleanup callback:
129 $r->pool->cleanup_register('foo');
131 "clear"
133 Clear all memory in the pool and run all the registered cleanups. This
134 also destroys all sub-pools.
135 $pool->clear();
137 obj: $pool ( "APR::Pool object" )
139 The pool to clear
140 ret: no return value
142 since: 2.0.00
143 This method differs from destroy() in that it is not freeing the
145 previously allocated, but allows the pool to re-use it for the future
146 memory allocations.
147 "DESTROY"
149 "DESTROY" is an alias to "destroy". It's there so that custom
150 "APR::Pool" objects will get properly cleaned up, when the pool object
151 goes out of scope. If you ever want to destroy an "APR::Pool" object
152 before it goes out of scope, use "destroy".
153 since: 2.0.00
155 "destroy"
157 Destroy the pool.
158 $pool->destroy();
160 obj: $pool ( "APR::Pool object" )
162 The pool to destroy
163 ret: no return value
165 since: 2.0.00
166 This method takes a similar action to clear() and then frees all the
168 memory.
169 "is_ancestor"
171 Determine if pool a is an ancestor of pool b
172 $ret = $pool_a->is_ancestor($pool_b);
174 obj: $pool_a ( "APR::Pool object" )
176 The pool to search
177 arg1: $pool_b ( "APR::Pool object" )
179 The pool to search for
180 ret: $ret ( integer )
182 True if $pool_a is an ancestor of $pool_b.
183 since: 2.0.00
185 For example create a sub-pool of a given pool and check that the pool
187 is an ancestor of that sub-pool:
188 use APR::Pool ();
190 my $pp = $r->pool;
191 my $sp = $pp->new();
192 $pp->is_ancestor($sp) or die "Don't mess with genes!";
193 "new"
195 Create a new sub-pool
196 my $pool_child = $pool_parent->new;
198 my $pool_child = APR::Pool->new;
199 obj: $pool_parent ( "APR::Pool object" )
201 The parent pool.
202 If you don't have a parent pool to create the sub-pool from, you
204 can use this object method as a class method, in which case the
205 sub-pool will be created from the global pool:
206 my $pool_child = APR::Pool->new;
208 ret: $pool_child ( "APR::Pool object" )
210 The child sub-pool
211 since: 2.0.00
213 "parent_get"
215 Get the parent pool
216 $parent_pool = $child_pool->parent_get();
218 obj: $child_pool ( "APR::Pool object" )
220 the child pool
221 ret: $parent_pool ( "APR::Pool object" )
223 the parent pool. "undef" if there is no parent pool (which is the
224 case for the top-most global pool).
225 since: 2.0.00
227 Example: Calculate how big is the pool's ancestry:
229 use APR::Pool ();
231 sub ancestry_count {
232 my $child = shift;
233 my $gen = 0;
234 while (my $parent = $child->parent_get) {
235 $gen++;
236 $child = $parent;
237 }
238 return $gen;
239 }
240 "tag"
242 Tag a pool (give it a name)
243 $pool->tag($tag);
245 obj: $pool ( "APR::Pool object" )
247 The pool to tag
248 arg1: $tag ( string )
250 The tag (some unique string)
251 ret: no return value
253 since: 2.0.00
254 Each pool can be tagged with a unique label. This can prove useful when
256 doing low level apr_pool C tracing (when apr is compiled with
257 "-DAPR_POOL_DEBUG"). It allows you to grep(1) for the tag you have set,
258 to single out the traces relevant to you.
259 Though there is no way to get read the tag value, since APR doesn't
261 provide such an accessor method.
262
264 "APR::Pool" also provides auto-generated Perl interface for a few other
265 methods which aren't tested at the moment and therefore their API is a
266 subject to change. These methods will be finalized later as a need
267 arises. If you want to rely on any of the following methods please
268 contact the the mod_perl development mailing list so we can help each
269 other take the steps necessary to shift the method to an officially
270 supported API.
271 "cleanup_for_exec"
273 META: Autogenerated - needs to be reviewed/completed
274 Preparing for exec() --- close files, etc., but *don't* flush I/O
276 buffers, *don't* wait for subprocesses, and *don't* free any memory.
277 Run all of the child_cleanups, so that any unnecessary files are closed
278 because we are about to exec a new program
279 ret: no return value
281 since: subject to change
282
284 mod_perl 2.0 documentation.
285
287 mod_perl 2.0 and its core modules are copyrighted under The Apache
288 Software License, Version 2.0.
289
291 The mod_perl development team and numerous contributors.
292perl v5.36.0 2023-01-19 docs::api::APR::Pool(3)