1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * mod_example_ipc -- Apache sample module
20 * This module illustrates the use in an Apache 2.x module of the Interprocess
21 * Communications routines that come with APR. It is example code, and not meant
22 * to be used in a production server.
24 * To play with this sample module first compile it into a DSO file and install
25 * it into Apache's modules directory by running:
27 * $ /path/to/apache2/bin/apxs -c -i mod_example_ipc.c
29 * Then activate it in Apache's httpd.conf file for instance for the URL
30 * /example_ipc in as follows:
33 * LoadModule example_ipc_module modules/mod_example_ipc.so
34 * <Location /example_ipc>
35 * SetHandler example_ipc
38 * Then restart Apache via
40 * $ /path/to/apache2/bin/apachectl restart
42 * The module allocates a counter in shared memory, which is incremented by the
43 * request handler under a mutex. After installation, activate the handler by
44 * hitting the URL configured above with ab at various concurrency levels to see
45 * how mutex contention affects server performance.
49 #include "apr_strings.h"
52 #include "http_config.h"
54 #include "http_protocol.h"
55 #include "ap_config.h"
57 #if !defined(OS2) && !defined(WIN32) && !defined(BEOS) && !defined(NETWARE)
59 #define MOD_EXIPC_SET_MUTEX_PERMS /* XXX Apache should define something */
62 #if APR_HAVE_SYS_TYPES_H
63 #include <sys/types.h>
69 #define HTML_HEADER "<html>\n<head>\n<title>Mod_example_IPC Status Page " \
70 "</title>\n</head>\n<body>\n<h1>Mod_example_IPC Status</h1>\n"
71 #define HTML_FOOTER "</body>\n</html>\n"
73 /* Number of microseconds to camp out on the mutex */
75 /* Maximum number of times we camp out before giving up */
77 /* Number of microseconds the handler sits on the lock once acquired. */
78 #define SLEEPYTIME 1000
80 apr_shm_t *exipc_shm; /* Pointer to shared memory block */
81 char *shmfilename; /* Shared memory file name, used on some systems */
82 apr_global_mutex_t *exipc_mutex; /* Lock around shared memory segment access */
83 char *mutexfilename; /* Lock file name, used on some systems */
85 /* Data structure for shared memory block */
86 typedef struct exipc_data {
88 /* More fields if necessary */
92 * Clean up the shared memory block. This function is registered as
93 * cleanup function for the configuration pool, which gets called
94 * on restarts. It assures that the new children will not talk to a stale
95 * shared memory segment.
97 static apr_status_t shm_cleanup_wrapper(void *unused) {
99 return apr_shm_destroy(exipc_shm);
105 * This routine is called in the parent, so we'll set up the shared
106 * memory segment and mutex here.
109 static int exipc_post_config(apr_pool_t *pconf, apr_pool_t *plog,
110 apr_pool_t *ptemp, server_rec *s)
112 void *data; /* These two help ensure that we only init once. */
113 const char *userdata_key;
120 * The following checks if this routine has been called before.
121 * This is necessary because the parent process gets initialized
122 * a couple of times as the server starts up, and we don't want
123 * to create any more mutexes and shared memory segments than
124 * we're actually going to use.
126 * The key needs to be unique for the entire web server, so put
127 * the module name in it.
129 userdata_key = "example_ipc_init_module";
130 apr_pool_userdata_get(&data, userdata_key, s->process->pool);
133 * If no data was found for our key, this must be the first
134 * time the module is initialized. Put some data under that
137 apr_pool_userdata_set((const void *) 1, userdata_key,
138 apr_pool_cleanup_null, s->process->pool);
140 } /* Kilroy was here */
143 * Both the shared memory and mutex allocation routines take a
144 * file name. Depending on system-specific implementation of these
145 * routines, that file may or may not actually be created. We'd
146 * like to store those files in the operating system's designated
147 * temporary directory, which APR can point us to.
149 rs = apr_temp_dir_get(&tempdir, pconf);
150 if (APR_SUCCESS != rs) {
151 ap_log_error(APLOG_MARK, APLOG_ERR, rs, s,
152 "Failed to find temporary directory");
153 return HTTP_INTERNAL_SERVER_ERROR;
156 /* Create the shared memory segment */
159 * Create a unique filename using our pid. This information is
160 * stashed in the global variable so the children inherit it.
162 shmfilename = apr_psprintf(pconf, "%s/httpd_shm.%ld", tempdir,
165 /* Now create that segment */
166 rs = apr_shm_create(&exipc_shm, sizeof(exipc_data),
167 (const char *) shmfilename, pconf);
168 if (APR_SUCCESS != rs) {
169 ap_log_error(APLOG_MARK, APLOG_ERR, rs, s,
170 "Failed to create shared memory segment on file %s",
172 return HTTP_INTERNAL_SERVER_ERROR;
175 /* Created it, now let's zero it out */
176 base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
179 /* Create global mutex */
182 * Create another unique filename to lock upon. Note that
183 * depending on OS and locking mechanism of choice, the file
184 * may or may not be actually created.
186 mutexfilename = apr_psprintf(pconf, "%s/httpd_mutex.%ld", tempdir,
187 (long int) getpid());
189 rs = apr_global_mutex_create(&exipc_mutex, (const char *) mutexfilename,
190 APR_LOCK_DEFAULT, pconf);
191 if (APR_SUCCESS != rs) {
192 ap_log_error(APLOG_MARK, APLOG_ERR, rs, s,
193 "Failed to create mutex on file %s",
195 return HTTP_INTERNAL_SERVER_ERROR;
199 * After the mutex is created, its permissions need to be adjusted
200 * on unix platforms so that the child processe can acquire
201 * it. This call takes care of that. The preprocessor define was
202 * set up early in this source file since Apache doesn't provide
205 #ifdef MOD_EXIPC_SET_MUTEX_PERMS
206 rs = ap_unixd_set_global_mutex_perms(exipc_mutex);
207 if (APR_SUCCESS != rs) {
208 ap_log_error(APLOG_MARK, APLOG_CRIT, rs, s,
209 "Parent could not set permissions on Example IPC "
210 "mutex: check User and Group directives");
211 return HTTP_INTERNAL_SERVER_ERROR;
213 #endif /* MOD_EXIPC_SET_MUTEX_PERMS */
216 * Destroy the shm segment when the configuration pool gets destroyed. This
217 * happens on server restarts. The parent will then (above) allocate a new
218 * shm segment that the new children will bind to.
220 apr_pool_cleanup_register(pconf, NULL, shm_cleanup_wrapper,
221 apr_pool_cleanup_null);
226 * This routine gets called when a child inits. We use it to attach
227 * to the shared memory segment, and reinitialize the mutex.
230 static void exipc_child_init(apr_pool_t *p, server_rec *s)
235 * Re-open the mutex for the child. Note we're reusing
236 * the mutex pointer global here.
238 rs = apr_global_mutex_child_init(&exipc_mutex,
239 (const char *) mutexfilename,
241 if (APR_SUCCESS != rs) {
242 ap_log_error(APLOG_MARK, APLOG_CRIT, rs, s,
243 "Failed to reopen mutex on file %s",
245 /* There's really nothing else we can do here, since This
246 * routine doesn't return a status. If this ever goes wrong,
247 * it will turn Apache into a fork bomb. Let's hope it never
250 exit(1); /* Ugly, but what else? */
254 /* The sample content handler */
255 static int exipc_handler(request_rec *r)
259 apr_time_t startcamp;
260 apr_int64_t timecamped;
264 if (strcmp(r->handler, "example_ipc")) {
269 * The main function of the handler, aside from sending the
270 * status page to the client, is to increment the counter in
271 * the shared memory segment. This action needs to be mutexed
272 * out using the global mutex.
276 * First, acquire the lock. This code is a lot more involved than
277 * it usually needs to be, because the process based trylock
278 * routine is not implemented on unix platforms. I left it in to
279 * show how it would work if trylock worked, and for situations
280 * and platforms where trylock works.
282 for (camped = 0, timecamped = 0; camped < MAXCAMP; camped++) {
283 rs = apr_global_mutex_trylock(exipc_mutex);
284 if (APR_STATUS_IS_EBUSY(rs)) {
286 } else if (APR_SUCCESS == rs) {
288 break; /* Get out of the loop */
289 } else if (APR_STATUS_IS_ENOTIMPL(rs)) {
290 /* If it's not implemented, just hang in the mutex. */
291 startcamp = apr_time_now();
292 rs = apr_global_mutex_lock(exipc_mutex);
293 timecamped = (apr_int64_t) (apr_time_now() - startcamp);
294 if (APR_SUCCESS == rs) {
296 break; /* Out of the loop */
298 /* Some error, log and bail */
299 ap_log_error(APLOG_MARK, APLOG_ERR, rs, r->server,
300 "Child %ld failed to acquire lock",
302 break; /* Out of the loop without having the lock */
305 /* Some other error, log and bail */
306 ap_log_error(APLOG_MARK, APLOG_ERR, rs, r->server,
307 "Child %ld failed to try and acquire lock",
309 break; /* Out of the loop without having the lock */
313 * The only way to get to this point is if the trylock worked
314 * and returned BUSY. So, bump the time and try again
316 timecamped += CAMPOUT;
317 ap_log_error(APLOG_MARK, APLOG_NOERRNO | APLOG_NOTICE,
318 0, r->server, "Child %ld camping out on mutex for %d "
320 (long int) getpid(), timecamped);
321 } /* Lock acquisition loop */
323 /* Sleep for a millisecond to make it a little harder for
324 * httpd children to acquire the lock.
326 apr_sleep(SLEEPYTIME);
328 r->content_type = "text/html";
330 if (!r->header_only) {
331 ap_rputs(HTML_HEADER, r);
333 /* Increment the counter */
334 base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
336 /* Send a page with our pid and the new value of the counter. */
337 ap_rprintf(r, "<p>Lock acquired after %ld microseoncds.</p>\n",
338 (long int) timecamped);
339 ap_rputs("<table border=\"1\">\n", r);
340 ap_rprintf(r, "<tr><td>Child pid:</td><td>%d</td></tr>\n",
342 ap_rprintf(r, "<tr><td>Counter:</td><td>%u</td></tr>\n",
343 (unsigned int)base->counter);
344 ap_rputs("</table>\n", r);
347 * Send a page saying that we couldn't get the lock. Don't say
348 * what the counter is, because without the lock the value could
351 ap_rprintf(r, "<p>Child %d failed to acquire lock "
352 "after camping out for %d microseconds.</p>\n",
353 (int) getpid(), (int) timecamped);
355 ap_rputs(HTML_FOOTER, r);
356 } /* r->header_only */
358 /* Release the lock */
360 rs = apr_global_mutex_unlock(exipc_mutex);
361 /* Swallowing the result because what are we going to do with it at
368 static void exipc_register_hooks(apr_pool_t *p)
370 ap_hook_post_config(exipc_post_config, NULL, NULL, APR_HOOK_MIDDLE);
371 ap_hook_child_init(exipc_child_init, NULL, NULL, APR_HOOK_MIDDLE);
372 ap_hook_handler(exipc_handler, NULL, NULL, APR_HOOK_MIDDLE);
375 /* Dispatch list for API hooks */
376 module AP_MODULE_DECLARE_DATA example_ipc_module = {
377 STANDARD20_MODULE_STUFF,
378 NULL, /* create per-dir config structures */
379 NULL, /* merge per-dir config structures */
380 NULL, /* create per-server config structures */
381 NULL, /* merge per-server config structures */
382 NULL, /* table of config file commands */
383 exipc_register_hooks /* register hooks */