1docs::api::Apache2::SizUesLeirmiCto(n3t)ributed Perl Docduomcesn:t:aatpiio:n:Apache2::SizeLimit(3)
2
6 Apache2::SizeLimit - Because size does matter.
7
9 This module allows you to kill off Apache httpd processes if they grow
10 too large. You can choose to set up the process size limiter to check
11 the process size on every request:
12 # in your startup.pl, or a <Perl> section:
14 use Apache2::SizeLimit;
15 # sizes are in KB
16 $Apache2::SizeLimit::MAX_PROCESS_SIZE = 12000; # 12MB
17 $Apache2::SizeLimit::MIN_SHARE_SIZE = 6000; # 6MB
18 $Apache2::SizeLimit::MAX_UNSHARED_SIZE = 5000; # 5MB
19 # in your httpd.conf:
21 PerlCleanupHandler Apache2::SizeLimit
22 Or you can just check those requests that are likely to get big, such
24 as CGI requests. This way of checking is also easier for those who are
25 mostly just running CGI scripts under "ModPerl::Registry":
26 # in your script:
28 use Apache2::SizeLimit;
29 # sizes are in KB
30 Apache2::SizeLimit::setmax(12000);
31 Apache2::SizeLimit::setmin(6000);
32 Apache2::SizeLimit::setmax_unshared(5000);
33 This will work in places where you are using "SetHandler perl-script"
35 or anywhere you enable "PerlOptions +GlobalRequest". If you want to
36 avoid turning on "GlobalRequest", you can pass an "Apache2::RequestRec"
37 object as the second argument in these subs:
38 my $r = shift; # if you don't have $r already
40 Apache2::SizeLimit::setmax(12000, $r);
41 Apache2::SizeLimit::setmin(6000, $r);
42 Apache2::SizeLimit::setmax_unshared(5000, $r);
43 Since checking the process size can take a few system calls on some
45 platforms (e.g. linux), you may want to only check the process size
46 every N times. To do so, put this in your startup.pl or CGI:
47 $Apache2::SizeLimit::CHECK_EVERY_N_REQUESTS = 2;
49 This will only check the process size every other time the process size
51 checker is called.
52
54 This module is highly platform dependent, please read the Caveats sec‐
55 tion. It also does not work under threaded MPMs.
56 This module was written in response to questions on the mod_perl mail‐
58 ing list on how to tell the httpd process to exit if it gets too big.
59 Actually there are two big reasons your httpd children will grow.
61 First, it could have a bug that causes the process to increase in size
62 dramatically, until your system starts swapping. Second, it may just
63 do things that requires a lot of memory, and the more different kinds
64 of requests your server handles, the larger the httpd processes grow
65 over time.
66 This module will not really help you with the first problem. For that
68 you should probably look into "Apache2::Resource" or some other means
69 of setting a limit on the data size of your program. BSD-ish systems
70 have "setrlimit()" which will croak your memory gobbling processes.
71 However it is a little violent, terminating your process in
72 mid-request.
73 This module attempts to solve the second situation where your process
75 slowly grows over time. The idea is to check the memory usage after
76 every request, and if it exceeds a threshold, exit gracefully.
77 By using this module, you should be able to discontinue using the
79 Apache configuration directive "MaxRequestsPerChild", although you can
80 use both if you are feeling paranoid. Most users use the technique
81 shown in this module and set their "MaxRequestsPerChild" value to 0.
82
84 In addition to simply checking the total size of a process, this module
85 can factor in how much of the memory used by the process is actually
86 being shared by copy-on-write. If you don't understand how memory is
87 shared in this way, take a look at the extensive documentation at
88 http://perl.apache.org/docs/.
89 You can take advantage of the shared memory information by setting a
91 minimum shared size and/or a maximum unshared size. Experience on one
92 heavily trafficked mod_perl site showed that setting maximum unshared
93 size and leaving the others unset is the most effective policy. This
94 is because it only kills off processes that are truly using too much
95 physical RAM, allowing most processes to live longer and reducing the
96 process churn rate.
97
99 This module is platform-dependent, since finding the size of a process
100 is pretty different from OS to OS, and some platforms may not be sup‐
101 ported. In particular, the limits on minimum shared memory and maximum
102 shared memory are currently only supported on Linux and BSD. If you
103 can contribute support for another OS, please do.
104 Supported OSes
106 linux
108 For linux we read the process size out of /proc/self/statm. This
109 seems to be fast enough on modern systems. If you are worried about
110 performance, try setting the "CHECK_EVERY_N_REQUESTS" option.
111 Since linux 2.6 /proc/self/statm does not report the amount of mem‐
113 ory shared by the copy-on-write mechanism as shared memory. Hence
114 decisions made on the basis of "MAX_UNSHARED_SIZE" or
115 "MIN_SHARE_SIZE" are inherently wrong.
116 To correct the situation there is a patch to the linux kernel that
118 adds a /proc/self/smaps entry for each process. At the time of this
119 writing the patch is included in the mm-tree (linux-2.6.13-rc4-mm1)
120 and is expected to make it into the vanilla kernel in the near
121 future.
122 /proc/self/smaps reports various sizes for each memory segment of a
124 process and allows to count the amount of shared memory correctly.
125 If "Apache2::SizeLimit" detects a kernel that supports
127 /proc/self/smaps and if the "Linux::Smaps" module is installed it
128 will use them instead of /proc/self/statm. You can prevent
129 "Apache2::SizeLimit" from using /proc/self/smaps and turn on the
130 old behaviour by setting $Apache2::SizeLimit::USE_SMAPS to 0 before
131 the first check.
132 "Apache2::SizeLimit" also resets $Apache2::SizeLimit::USE_SMAPS to
134 0 if it somehow decides not to use /proc/self/smaps. Thus, you can
135 check it to determine what is actually used.
136 NOTE: Reading /proc/self/smaps is expensive compared to
138 /proc/self/statm. It must look at each page table entry of a
139 process. Further, on multiprocessor systems the access is synchro‐
140 nized with spinlocks. Hence, you are encouraged to set the
141 "CHECK_EVERY_N_REQUESTS" option.
142 The following example shows the effect of copy-on-write:
144 <Perl>
146 require Apache2::SizeLimit;
147 package X;
148 use strict;
149 use Apache2::RequestRec ();
150 use Apache2::RequestIO ();
151 use Apache2::Const -compile=>qw(OK);
152 my $x= "a" x (1024*1024);
154 sub handler {
156 my $r = shift;
157 my ($size, $shared) = $Apache2::SizeLimit::HOW_BIG_IS_IT->();
158 $x =~ tr/a/b/;
159 my ($size2, $shared2) = $Apache2::SizeLimit::HOW_BIG_IS_IT->();
160 $r->content_type('text/plain');
161 $r->print("1: size=$size shared=$shared\n");
162 $r->print("2: size=$size2 shared=$shared2\n");
163 return Apache2::Const::OK;
164 }
165 </Perl>
166 <Location /X>
168 SetHandler modperl
169 PerlResponseHandler X
170 </Location>
171 The parent apache allocates a megabyte for the string in $x. The
173 "tr"-command then overwrites all "a" with "b" if the handler is
174 called with an argument. This write is done in place, thus, the
175 process size doesn't change. Only $x is not shared anymore by means
176 of copy-on-write between the parent and the child.
177 If /proc/self/smaps is available curl shows:
179 r2@s93:~/work/mp2> curl http://localhost:8181/X
181 1: size=13452 shared=7456
182 2: size=13452 shared=6432
183 Shared memory has lost 1024 kB. The process' overall size remains
185 unchanged.
186 Without /proc/self/smaps it says:
188 r2@s93:~/work/mp2> curl http://localhost:8181/X
190 1: size=13052 shared=3628
191 2: size=13052 shared=3636
192 One can see the kernel lies about the shared memory. It simply
194 doesn't count copy-on-write pages as shared.
195 Solaris 2.6 and above
197 For Solaris we simply retrieve the size of /proc/self/as, which
198 contains the address-space image of the process, and convert to KB.
199 Shared memory calculations are not supported.
200 NOTE: This is only known to work for solaris 2.6 and above. Evi‐
202 dently the /proc filesystem has changed between 2.5.1 and 2.6. Can
203 anyone confirm or deny?
204 BSD Uses "BSD::Resource::getrusage()" to determine process size. This
206 is pretty efficient (a lot more efficient than reading it from the
207 /proc fs anyway).
208 AIX?
210 Uses "BSD::Resource::getrusage()" to determine process size. Not
211 sure if the shared memory calculations will work or not. AIX
212 users?
213 Win32
215 Under mod_perl 1, SizeLimit provided basic functionality by using
216 "Win32::API" to access process memory information. This worked
217 because there was only one mod_perl thread. With mod_perl 2, Win32
218 runs a true threaded MPM, which unfortunately means that we can't
219 tell the size of each interpreter. Win32 support is disabled until
220 a solution for this can be found.
221 If your platform is not supported, and if you can tell us how to check
223 for the size of a process under your OS (in KB), then we will add it to
224 the list. The more portable/efficient the solution, the better, of
225 course.
226 Supported MPMs
228 At this time, "Apache2::SizeLimit" does not support use under threaded
230 MPMs. This is because there is no efficient way to get the memory
231 usage of a thread, or make a thread exit cleanly. Suggestions and
232 patches are welcome on the mod_perl dev mailing list.
233
235 mod_perl 2.0 and its core modules are copyrighted under The Apache
236 Software License, Version 2.0.
237
239 Doug Bagley <doug+modperl bagley.org>, channeling Procrustes.
240 Brian Moseley <ix maz.org>: Solaris 2.6 support
242 Doug Steinwand and Perrin Harkins <perrin elem.com>: added support for
244 shared memory and additional diagnostic info
245 Matt Phillips <mphillips virage.com> and Mohamed Hendawi <mhendawi
247 virage.com>: Win32 support
248 Torsten Foertsch <torsten.foertsch gmx.net>: Linux::Smaps support
250perl v5.8.8 2006-11-19 docs::api::Apache2::SizeLimit(3)