1docs::api::APR::Pool(3)User Contributed Perl Documentatiodnocs::api::APR::Pool(3)
2
3
4

NAME

6       APR::Pool - Perl API for APR pools
7

Synopsis

9         use APR::Pool ();
10
11         my $sp = $r->pool->new;
12         my $sp2 = APR::Pool->new;
13
14         # $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
23         # $sp4 and $sp are the same pool (though you can't
24         # compare the handle as variables)
25         my $sp4 = $sp3->parent_get;
26
27
28         # register a dummy cleanup function
29         # that just prints the passed args
30         $sp->cleanup_register(sub { print @{ $_[0] || [] } }, [1..3]);
31
32         # tag the pool
33         $sp->tag("My very best pool");
34
35         # clear the pool
36         $sp->clear();
37
38         # destroy sub pool
39         $sp2->destroy;
40

Description

42       "APR::Pool" provides an access to APR pools, which are used for an easy
43       memory management.
44
45       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
52       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
61       If you need to create a new pool, you can always do that via the
62       "new()" method.
63

API

65       "APR::Pool" provides the following functions and/or methods:
66
67   "cleanup_register"
68       Register cleanup callback to run
69
70         $pool->cleanup_register($callback);
71         $pool->cleanup_register($callback, $arg);
72
73       obj: $pool ( "APR::Pool object" )
74           The pool object to register the cleanup callback for
75
76       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
80       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
84           To pass more than one argument, use an ARRAY or a HASH reference
85
86       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
90           printing it to the error_log. However, a $SIG{__WARN__} handler can
91           be used to catch them.
92
93             $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
101           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
106       since: 2.0.00
107
108       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
112       Examples:
113
114       No arguments, using anon sub as a cleanup callback:
115
116         $r->pool->cleanup_register(sub { warn "running cleanup" });
117
118       One or more arguments using a cleanup code reference:
119
120         $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
128       No arguments, using a function name as a cleanup callback:
129
130         $r->pool->cleanup_register('foo');
131
132   "clear"
133       Clear all memory in the pool and run all the registered cleanups. This
134       also destroys all sub-pools.
135
136         $pool->clear();
137
138       obj: $pool ( "APR::Pool object" )
139           The pool to clear
140
141       ret: no return value
142       since: 2.0.00
143
144       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
148   "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
154       since: 2.0.00
155
156   "destroy"
157       Destroy the pool.
158
159         $pool->destroy();
160
161       obj: $pool ( "APR::Pool object" )
162           The pool to destroy
163
164       ret: no return value
165       since: 2.0.00
166
167       This method takes a similar action to "clear()" and then frees all the
168       memory.
169
170   "is_ancestor"
171       Determine if pool a is an ancestor of pool b
172
173         $ret = $pool_a->is_ancestor($pool_b);
174
175       obj: $pool_a ( "APR::Pool object" )
176           The pool to search
177
178       arg1: $pool_b ( "APR::Pool object" )
179           The pool to search for
180
181       ret: $ret ( integer )
182           True if $pool_a is an ancestor of $pool_b.
183
184       since: 2.0.00
185
186       For example create a sub-pool of a given pool and check that the pool
187       is an ancestor of that sub-pool:
188
189         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
194   "new"
195       Create a new sub-pool
196
197         my $pool_child = $pool_parent->new;
198         my $pool_child = APR::Pool->new;
199
200       obj: $pool_parent ( "APR::Pool object" )
201           The parent pool.
202
203           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
207             my $pool_child = APR::Pool->new;
208
209       ret: $pool_child ( "APR::Pool object" )
210           The child sub-pool
211
212       since: 2.0.00
213
214   "parent_get"
215       Get the parent pool
216
217         $parent_pool = $child_pool->parent_get();
218
219       obj: $child_pool ( "APR::Pool object" )
220           the child pool
221
222       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
226       since: 2.0.00
227
228       Example: Calculate how big is the pool's ancestry:
229
230         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
241   "tag"
242       Tag a pool (give it a name)
243
244         $pool->tag($tag);
245
246       obj: $pool ( "APR::Pool object" )
247           The pool to tag
248
249       arg1: $tag ( string )
250           The tag (some unique string)
251
252       ret: no return value
253       since: 2.0.00
254
255       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
260       Though there is no way to get read the tag value, since APR doesn't
261       provide such an accessor method.
262

Unsupported API

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
272   "cleanup_for_exec"
273       META: Autogenerated - needs to be reviewed/completed
274
275       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
280       ret: no return value
281       since: subject to change
282

See Also

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

Authors

291       The mod_perl development team and numerous contributors.
292
293
294
295perl v5.30.0                      2019-10-07           docs::api::APR::Pool(3)
Impressum