1Apache::SizeLimit(3)  User Contributed Perl Documentation Apache::SizeLimit(3)
2
3
4

NAME

6       Apache::SizeLimit - Because size does matter.
7

SYNOPSIS

9           PerlModule Apache::SizeLimit
10
11           <Perl>
12            Apache::SizeLimit->set_max_process_size(150_000);   # Max size in KB
13            Apache::SizeLimit->set_min_shared_size(10_000);     # Min share in KB
14            Apache::SizeLimit->set_max_unshared_size(120_000);  # Max unshared size in KB
15           </Perl>
16
17           PerlCleanupHandler Apache::SizeLimit
18

DESCRIPTION

20       ******************************** NOIICE *******************
21
22          This version is only for httpd 1.3.x and mod_perl 1.x
23          series.
24
25          For httpd 2.x / mod_perl 2.x Apache2::SizeLimit
26          documentation please read the perldoc in
27          lib/Apache2/SizeLimit.pm
28
29       ******************************** NOTICE *******************
30
31       This module allows you to kill off Apache httpd processes if they grow
32       too large. You can make the decision to kill a process based on its
33       overall size, by setting a minimum limit on shared memory, or a maximum
34       on unshared memory.
35
36       You can set limits for each of these sizes, and if any limit is
37       exceeded, the process will be killed.
38
39       You can also limit the frequency that these sizes are checked so that
40       this module only checks every N requests.
41
42       This module is highly platform dependent, please read the "PER-PLATFORM
43       BEHAVIOR" section for details. It is possible that this module simply
44       does not support your platform.
45

API

47       You can set set the size limits from a Perl module or script loaded by
48       Apache by calling the appropriate class method on "Apache::SizeLimit":
49
50       •   Apache::SizeLimit->set_max_process_size($size)
51
52           This sets the maximum size of the process, including both shared
53           and unshared memory.
54
55       •   Apache::SizeLimit->set_max_unshared_size($size)
56
57           This sets the maximum amount of unshared memory the process can
58           use.
59
60       •   Apache::SizeLimit->set_min_shared_size($size)
61
62           This sets the minimum amount of shared memory the process must
63           have.
64
65       The two methods related to shared memory size are effectively a no-op
66       if the module cannot determine the shared memory size for your
67       platform. See "PER-PLATFORM BEHAVIOR" for more details.
68
69   Running the handler()
70       There are several ways to make this module actually run the code to
71       kill a process.
72
73       The simplest is to make "Apache::SizeLimit" a "PerlCleanupHandler" in
74       your Apache config:
75
76           PerlCleanupHandler Apache::SizeLimit
77
78       This will ensure that "Apache::SizeLimit->handler()" is run for all
79       requests.
80
81       If you want to combine this module with a cleanup handler of your own,
82       make sure that "Apache::SizeLimit" is the last handler run:
83
84           PerlCleanupHandler  Apache::SizeLimit My::CleanupHandler
85
86       Remember, mod_perl will run stacked handlers from right to left, as
87       they're defined in your configuration.
88
89       If you have some cleanup code you need to run, but stacked handlers
90       aren't appropriate for your setup, you can also explicitly call the
91       "Apache::SizeLimit->handler()" function from your own cleanup handler:
92
93           package My::CleanupHandler
94
95           sub handler {
96               my $r = shift;
97
98               # Causes File::Temp to remove any temp dirs created during the
99               # request
100               File::Temp::cleanup();
101
102               return Apache::SizeLimit->handler($r);
103           }
104
105       •   Apache::SizeLimit->add_cleanup_handler($r)
106
107           You can call this method inside a request to run
108           "Apache::SizeLimit"'s handler() method for just that request. It's
109           safe to call this method repeatedly -- the cleanup will only be run
110           once per request.
111
112   Checking Every N Requests
113       Since checking the process size can take a few system calls on some
114       platforms (e.g. linux), you may not want to check the process size for
115       every request.
116
117       •   Apache::SizeLimit->set_check_interval($interval)
118
119           Calling this causes "Apache::SizeLimit" to only check the process
120           size every $interval requests. If you want this to affect all
121           processes, make sure to call this during server startup.
122

SHARED MEMORY OPTIONS

124       In addition to simply checking the total size of a process, this module
125       can factor in how much of the memory used by the process is actually
126       being shared by copy-on-write. If you don't understand how memory is
127       shared in this way, take a look at the mod_perl docs at
128       http://perl.apache.org/docs/.
129
130       You can take advantage of the shared memory information by setting a
131       minimum shared size and/or a maximum unshared size. Experience on one
132       heavily trafficked mod_perl site showed that setting maximum unshared
133       size and leaving the others unset is the most effective policy. This is
134       because it only kills off processes that are truly using too much
135       physical RAM, allowing most processes to live longer and reducing the
136       process churn rate.
137

PER-PLATFORM BEHAVIOR

139       This module is highly platform dependent, since finding the size of a
140       process is different for each OS, and some platforms may not be
141       supported. In particular, the limits on minimum shared memory and
142       maximum shared memory are currently only supported on Linux and BSD.
143       If you can contribute support for another OS, patches are very welcome.
144
145       Currently supported OSes:
146
147   linux
148       For linux we read the process size out of /proc/self/statm. If you are
149       worried about performance, you can consider using
150       "Apache::SizeLimit->set_check_interval()" to reduce how often this read
151       happens.
152
153       As of linux 2.6, /proc/self/statm does not report the amount of memory
154       shared by the copy-on-write mechanism as shared memory. This means that
155       decisions made based on shared memory as reported by that interface are
156       inherently wrong.
157
158       However, as of the 2.6.14 release of the kernel, there is
159       /proc/self/smaps entry for each process. /proc/self/smaps reports
160       various sizes for each memory segment of a process and allows us to
161       count the amount of shared memory correctly.
162
163       If "Apache::SizeLimit" detects a kernel that supports /proc/self/smaps
164       and the "Linux::Smaps" module is installed it will use that module
165       instead of /proc/self/statm.
166
167       Reading /proc/self/smaps is expensive compared to /proc/self/statm. It
168       must look at each page table entry of a process.  Further, on
169       multiprocessor systems the access is synchronized with spinlocks.
170       Again, you might consider using
171       "Apache::SizeLimit->set_check_interval()".
172
173       Copy-on-write and Shared Memory
174
175       The following example shows the effect of copy-on-write:
176
177         <Perl>
178           require Apache::SizeLimit;
179           package X;
180           use strict;
181           use Apache::Constants qw(OK);
182
183           my $x = "a" x (1024*1024);
184
185           sub handler {
186             my $r = shift;
187             my ($size, $shared) = $Apache::SizeLimit->_check_size();
188             $x =~ tr/a/b/;
189             my ($size2, $shared2) = $Apache::SizeLimit->_check_size();
190             $r->content_type('text/plain');
191             $r->print("1: size=$size shared=$shared\n");
192             $r->print("2: size=$size2 shared=$shared2\n");
193             return OK;
194           }
195         </Perl>
196
197         <Location /X>
198           SetHandler modperl
199           PerlResponseHandler X
200         </Location>
201
202       The parent Apache process allocates memory for the string in $x. The
203       "tr"-command then overwrites all "a" with "b" if the handler is called
204       with an argument. This write is done in place, thus, the process size
205       doesn't change. Only $x is not shared anymore by means of copy-on-write
206       between the parent and the child.
207
208       If /proc/self/smaps is available curl shows:
209
210         r2@s93:~/work/mp2> curl http://localhost:8181/X
211         1: size=13452 shared=7456
212         2: size=13452 shared=6432
213
214       Shared memory has lost 1024 kB. The process' overall size remains
215       unchanged.
216
217       Without /proc/self/smaps it says:
218
219         r2@s93:~/work/mp2> curl http://localhost:8181/X
220         1: size=13052 shared=3628
221         2: size=13052 shared=3636
222
223       One can see the kernel lies about the shared memory. It simply doesn't
224       count copy-on-write pages as shared.
225
226   solaris 2.6 and above
227       For solaris we simply retrieve the size of /proc/self/as, which
228       contains the address-space image of the process, and convert to KB.
229       Shared memory calculations are not supported.
230
231       NOTE: This is only known to work for solaris 2.6 and above. Evidently
232       the /proc filesystem has changed between 2.5.1 and 2.6. Can anyone
233       confirm or deny?
234
235   BSD (and OSX)
236       Uses BSD::Resource::getrusage() to determine process size.  This is
237       pretty efficient (a lot more efficient than reading it from the /proc
238       fs anyway).
239
240       According to recent tests on OSX (July, 2006), "BSD::Resource" simply
241       reports zero for process and shared size on that platform, so OSX is
242       not supported by "Apache::SizeLimit".
243
244   AIX?
245       Uses BSD::Resource::getrusage() to determine process size.  Not sure if
246       the shared memory calculations will work or not.  AIX users?
247
248   Win32
249       Uses "Win32::API" to access process memory information.  "Win32::API"
250       can be installed under ActiveState perl using the supplied ppm utility.
251
252   Everything Else
253       If your platform is not supported, then please send a patch to check
254       the process size. The more portable/efficient/correct the solution the
255       better, of course.
256

ABOUT THIS MODULE

258       This module was written in response to questions on the mod_perl
259       mailing list on how to tell the httpd process to exit if it gets too
260       big.
261
262       Actually, there are two big reasons your httpd children will grow.
263       First, your code could have a bug that causes the process to increase
264       in size very quickly. Second, you could just be doing operations that
265       require a lot of memory for each request. Since Perl does not give
266       memory back to the system after using it, the process size can grow
267       quite large.
268
269       This module will not really help you with the first problem. For that
270       you should probably look into "Apache::Resource" or some other means of
271       setting a limit on the data size of your program.  BSD-ish systems have
272       setrlimit(), which will kill your memory gobbling processes.  However,
273       it is a little violent, terminating your process in mid-request.
274
275       This module attempts to solve the second situation, where your process
276       slowly grows over time. It checks memory usage after every request, and
277       if it exceeds a threshold, exits gracefully.
278
279       By using this module, you should be able to discontinue using the
280       Apache configuration directive MaxRequestsPerChild, although for some
281       folks, using both in combination does the job.
282

DEPRECATED APIS

284       Previous versions of this module documented three globals for defining
285       memory size limits:
286
287       •   $Apache::SizeLimit::MAX_PROCESS_SIZE
288
289       •   $Apache::SizeLimit::MIN_SHARE_SIZE
290
291       •   $Apache::SizeLimit::MAX_UNSHARED_SIZE
292
293       •   $Apache::SizeLimit::CHECK_EVERY_N_REQUESTS
294
295       •   $Apache::SizeLimit::USE_SMAPS
296
297       Direct use of these globals is deprecated, but will continue to work
298       for the foreseeable future.
299
300       It also documented three functions for use from registry scripts:
301
302       •   Apache::SizeLimit::setmax()
303
304       •   Apache::SizeLimit::setmin()
305
306       •   Apache::SizeLimit::setmax_unshared()
307
308       Besides setting the appropriate limit, these functions also add a
309       cleanup handler to the current request.
310

SUPPORT

312       The Apache-SizeLimit project is co-maintained by several developers,
313       who take turns at making CPAN releases. Therefore you may find several
314       CPAN directories containing Apache-SizeLimit releases. The best way to
315       find the latest release is to use http://search.cpan.org/.
316
317       If you have a question or you want to submit a bug report or make a
318       contribution, please do not email individual authors, but send an email
319       to the modperl <at> perl.apache.org mailing list. This list is
320       moderated, so unless you are subscribed to it, your message will have
321       to be approved first by a moderator. Therefore please allow some time
322       (up to a few days) for your post to propagate to the list.
323

AUTHOR

325       Doug Bagley <doug+modperl@bagley.org>, channeling Procrustes.
326
327       Brian Moseley <ix@maz.org>: Solaris 2.6 support
328
329       Doug Steinwand and Perrin Harkins <perrin@elem.com>: added support for
330       shared memory and additional diagnostic info
331
332       Matt Phillips <mphillips@virage.com> and Mohamed Hendawi
333       <mhendawi@virage.com>: Win32 support
334
335       Dave Rolsky <autarch@urth.org>, maintenance and fixes outside of
336       mod_perl tree (0.9+).
337
338
339
340perl v5.38.0                      2023-07-20              Apache::SizeLimit(3)