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 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
95       since: 2.0.00
96
97       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
101       Examples:
102
103       No arguments, using anon sub as a cleanup callback:
104
105         $r->pool->cleanup_register(sub { warn "running cleanup" });
106
107       One or more arguments using a cleanup code reference:
108
109         $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
117       No arguments, using a function name as a cleanup callback:
118
119         $r->pool->cleanup_register('foo');
120
121   "clear"
122       Clear all memory in the pool and run all the registered cleanups. This
123       also destroys all sub-pools.
124
125         $pool->clear();
126
127       obj: $pool ( "APR::Pool object" )
128           The pool to clear
129
130       ret: no return value
131       since: 2.0.00
132
133       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
137   "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
143       since: 2.0.00
144
145   "destroy"
146       Destroy the pool.
147
148         $pool->destroy();
149
150       obj: $pool ( "APR::Pool object" )
151           The pool to destroy
152
153       ret: no return value
154       since: 2.0.00
155
156       This method takes a similar action to "clear()" and then frees all the
157       memory.
158
159   "is_ancestor"
160       Determine if pool a is an ancestor of pool b
161
162         $ret = $pool_a->is_ancestor($pool_b);
163
164       obj: $pool_a ( "APR::Pool object" )
165           The pool to search
166
167       arg1: $pool_b ( "APR::Pool object" )
168           The pool to search for
169
170       ret: $ret ( integer )
171           True if $pool_a is an ancestor of $pool_b.
172
173       since: 2.0.00
174
175       For example create a sub-pool of a given pool and check that the pool
176       is an ancestor of that sub-pool:
177
178         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
183   "new"
184       Create a new sub-pool
185
186         my $pool_child = $pool_parent->new;
187         my $pool_child = APR::Pool->new;
188
189       obj: $pool_parent ( "APR::Pool object" )
190           The parent pool.
191
192           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
196             my $pool_child = APR::Pool->new;
197
198       ret: $pool_child ( "APR::Pool object" )
199           The child sub-pool
200
201       since: 2.0.00
202
203   "parent_get"
204       Get the parent pool
205
206         $parent_pool = $child_pool->parent_get();
207
208       obj: $child_pool ( "APR::Pool object" )
209           the child pool
210
211       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
215       since: 2.0.00
216
217       Example: Calculate how big is the pool's ancestry:
218
219         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
230   "tag"
231       Tag a pool (give it a name)
232
233         $pool->tag($tag);
234
235       obj: $pool ( "APR::Pool object" )
236           The pool to tag
237
238       arg1: $tag ( string )
239           The tag (some unique string)
240
241       ret: no return value
242       since: 2.0.00
243
244       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
249       Though there is no way to get read the tag value, since APR doesn't
250       provide such an accessor method.
251

Unsupported API

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
261   "cleanup_for_exec"
262       META: Autogenerated - needs to be reviewed/completed
263
264       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
269       ret: no return value
270       since: subject to change
271

See Also

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

Authors

280       The mod_perl development team and numerous contributors.
281
282
283
284perl v5.12.0                      2007-11-12           docs::api::APR::Pool(3)
Impressum