1Apache2::SizeLimit(3) User Contributed Perl DocumentationApache2::SizeLimit(3)
2
6 Apache2::SizeLimit - Because size does matter.
7
9 PerlLoadModule Apache2::SizeLimit
10 <Perl>
12 Apache2::SizeLimit->set_max_process_size(150_000); # Max size in KB
13 Apache2::SizeLimit->set_min_shared_size(10_000); # Min share in KB
14 Apache2::SizeLimit->set_max_unshared_size(120_000); # Max unshared size in KB
15 </Perl>
16 PerlCleanupHandler Apache2::SizeLimit
18
20 ******************************** NOIICE *******************
21 This version is only for httpd 2.x and mod_perl 2.x
23 series.
24 For httpd 1.3.x / mod_perl 1.x Apache::SizeLimit
26 documentation please read the perldoc in
27 lib/Apache/SizeLimit.pm
28 ******************************** NOTICE *******************
30 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 You can set limits for each of these sizes, and if any limit is
37 exceeded, the process will be killed.
38 You can also limit the frequency that these sizes are checked so that
40 this module only checks every N requests.
41 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
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 "Apache2::SizeLimit":
49 • Apache2::SizeLimit->set_max_process_size($size)
51 This sets the maximum size of the process, including both shared
53 and unshared memory.
54 • Apache2::SizeLimit->set_max_unshared_size($size)
56 This sets the maximum amount of unshared memory the process can
58 use.
59 • Apache2::SizeLimit->set_min_shared_size($size)
61 This sets the minimum amount of shared memory the process must
63 have.
64 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 Running the handler()
70 There are several ways to make this module actually run the code to
71 kill a process.
72 The simplest is to make "Apache2::SizeLimit" a "PerlCleanupHandler" in
74 your Apache config:
75 PerlCleanupHandler Apache2::SizeLimit
77 This will ensure that "Apache2::SizeLimit->handler()" is run for all
79 requests.
80 If you want to combine this module with a cleanup handler of your own,
82 make sure that "Apache2::SizeLimit" is the last handler run:
83 PerlCleanupHandler Apache2::SizeLimit My::CleanupHandler
85 Remember, mod_perl will run stacked handlers from right to left, as
87 they're defined in your configuration.
88 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 "Apache2::SizeLimit->handler()" function from your own cleanup handler:
92 package My::CleanupHandler
94 sub handler {
96 my $r = shift;
97 # Causes File::Temp to remove any temp dirs created during the
99 # request
100 File::Temp::cleanup();
101 return Apache2::SizeLimit->handler($r);
103 }
104 • Apache2::SizeLimit->add_cleanup_handler($r)
106 You can call this method inside a request to run
108 "Apache2::SizeLimit"'s "handler()" method for just that request.
109 It's safe to call this method repeatedly -- the cleanup will only
110 be run once per request.
111 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 • Apache2::SizeLimit->set_check_interval($interval)
118 Calling this causes "Apache2::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
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 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
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 Currently supported OSes:
146 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 "Apache2::SizeLimit->set_check_interval()" to reduce how often this
151 read happens.
152 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 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 If "Apache2::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 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 "Apache2::SizeLimit->set_check_interval()".
172 Copy-on-write and Shared Memory
174 The following example shows the effect of copy-on-write:
176 <Perl>
178 require Apache2::SizeLimit;
179 package X;
180 use strict;
181 use Apache2::Const -compile => qw(OK);
182 my $x = "a" x (1024*1024);
184 sub handler {
186 my $r = shift;
187 my ($size, $shared) = $Apache2::SizeLimit->_check_size();
188 $x =~ tr/a/b/;
189 my ($size2, $shared2) = $Apache2::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 <Location /X>
198 SetHandler modperl
199 PerlResponseHandler X
200 </Location>
201 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 If /proc/self/smaps is available curl shows:
209 r2@s93:~/work/mp2> curl http://localhost:8181/X
211 1: size=13452 shared=7456
212 2: size=13452 shared=6432
213 Shared memory has lost 1024 kB. The process' overall size remains
215 unchanged.
216 Without /proc/self/smaps it says:
218 r2@s93:~/work/mp2> curl http://localhost:8181/X
220 1: size=13052 shared=3628
221 2: size=13052 shared=3636
222 One can see the kernel lies about the shared memory. It simply doesn't
224 count copy-on-write pages as shared.
225 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 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 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 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 "Apache2::SizeLimit".
243 AIX?
245 Uses "BSD::Resource::getrusage()" to determine process size. Not sure
246 if the shared memory calculations will work or not. AIX users?
247 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 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
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 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 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.
273 However, it is a little violent, terminating your process in mid-
274 request.
275 This module attempts to solve the second situation, where your process
277 slowly grows over time. It checks memory usage after every request, and
278 if it exceeds a threshold, exits gracefully.
279 By using this module, you should be able to discontinue using the
281 Apache configuration directive MaxRequestsPerChild, although for some
282 folks, using both in combination does the job.
283
285 Previous versions of this module documented three globals for defining
286 memory size limits:
287 • $Apache2::SizeLimit::MAX_PROCESS_SIZE
289 • $Apache2::SizeLimit::MIN_SHARE_SIZE
291 • $Apache2::SizeLimit::MAX_UNSHARED_SIZE
293 • $Apache2::SizeLimit::CHECK_EVERY_N_REQUESTS
295 • $Apache2::SizeLimit::USE_SMAPS
297 Direct use of these globals is deprecated, but will continue to work
299 for the foreseeable future.
300 It also documented three functions for use from registry scripts:
302 • Apache2::SizeLimit::setmax()
304 • Apache2::SizeLimit::setmin()
306 • Apache2::SizeLimit::setmax_unshared()
308 Besides setting the appropriate limit, these functions also add a
310 cleanup handler to the current request. In the 2.x series of mod_perl
311 to use the deprecated functions, you must set PerlOptions
312 +GlobalRequest accordingly.
313
315 The Apache-SizeLimit project is co-maintained by several developers,
316 who take turns at making CPAN releases. Therefore you may find several
317 CPAN directories containing Apache-SizeLimit releases. The best way to
318 find the latest release is to use http://search.cpan.org/.
319 If you have a question or you want to submit a bug report or make a
321 contribution, please do not email individual authors, but send an email
322 to the modperl <at> perl.apache.org mailing list. This list is
323 moderated, so unless you are subscribed to it, your message will have
324 to be approved first by a moderator. Therefore please allow some time
325 (up to a few days) for your post to propagate to the list.
326
328 Doug Bagley <doug+modperl@bagley.org>, channeling Procrustes.
329 Brian Moseley <ix@maz.org>: Solaris 2.6 support
331 Doug Steinwand and Perrin Harkins <perrin@elem.com>: added support for
333 shared memory and additional diagnostic info
334 Matt Phillips <mphillips@virage.com> and Mohamed Hendawi
336 <mhendawi@virage.com>: Win32 support
337 Dave Rolsky <autarch@urth.org>, maintenance and fixes outside of
339 mod_perl tree (0.9+).
340perl v5.32.1 2021-01-26 Apache2::SizeLimit(3)