Apache HTTPD
mod_example_ipc.c
Go to the documentation of this file.
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
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
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.
15 */
16
17/*
18 * mod_example_ipc -- Apache sample module
19 *
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.
23 *
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:
26 *
27 * $ /path/to/apache2/bin/apxs -c -i mod_example_ipc.c
28 *
29 * Then activate it in Apache's httpd.conf file for instance for the URL
30 * /example_ipc in as follows:
31 *
32 * # httpd.conf
33 * LoadModule example_ipc_module modules/mod_example_ipc.so
34 * <Location /example_ipc>
35 * SetHandler example_ipc
36 * </Location>
37 *
38 * Then restart Apache via
39 *
40 * $ /path/to/apache2/bin/apachectl restart
41 *
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.
46 */
47
48#include "apr.h"
49#include "apr_strings.h"
50
51#include "httpd.h"
52#include "http_config.h"
53#include "http_core.h"
54#include "http_log.h"
55#include "http_protocol.h"
56#include "util_mutex.h"
57#include "ap_config.h"
58
59#if APR_HAVE_SYS_TYPES_H
60#include <sys/types.h>
61#endif
62#if APR_HAVE_UNISTD_H
63#include <unistd.h>
64#endif
65
66#define HTML_HEADER "<html>\n<head>\n<title>Mod_example_IPC Status Page " \
67 "</title>\n</head>\n<body>\n<h1>Mod_example_IPC Status</h1>\n"
68#define HTML_FOOTER "</body>\n</html>\n"
69
70/* Number of microseconds to camp out on the mutex */
71#define CAMPOUT 10
72/* Maximum number of times we camp out before giving up */
73#define MAXCAMP 10
74/* Number of microseconds the handler sits on the lock once acquired. */
75#define SLEEPYTIME 1000
76
77apr_shm_t *exipc_shm; /* Pointer to shared memory block */
78char *shmfilename; /* Shared memory file name, used on some systems */
79apr_global_mutex_t *exipc_mutex; /* Lock around shared memory segment access */
80static const char *exipc_mutex_type = "example-ipc-shm";
81
82/* Data structure for shared memory block */
83typedef struct exipc_data {
84 apr_uint64_t counter;
85 /* More fields if necessary */
86} exipc_data;
87
88/*
89 * Clean up the shared memory block. This function is registered as
90 * cleanup function for the configuration pool, which gets called
91 * on restarts. It assures that the new children will not talk to a stale
92 * shared memory segment.
93 */
94static apr_status_t shm_cleanup_wrapper(void *unused)
95{
96 if (exipc_shm)
97 return apr_shm_destroy(exipc_shm);
98 return OK;
99}
100
101/*
102 * This routine is called in the parent; we must register our
103 * mutex type before the config is processed so that users can
104 * adjust the mutex settings using the Mutex directive.
105 */
106
113
114/*
115 * This routine is called in the parent, so we'll set up the shared
116 * memory segment and mutex here.
117 */
118
119static int exipc_post_config(apr_pool_t *pconf, apr_pool_t *plog,
120 apr_pool_t *ptemp, server_rec *s)
121{
122 apr_status_t rs;
123 exipc_data *base;
124 const char *tempdir;
125
126
127 /*
128 * Do nothing if we are not creating the final configuration.
129 * The parent process gets initialized a couple of times as the
130 * server starts up, and we don't want to create any more mutexes
131 * and shared memory segments than we're actually going to use.
132 */
133 if (ap_state_query(AP_SQ_MAIN_STATE) == AP_SQ_MS_CREATE_PRE_CONFIG)
134 return OK;
135
136 /*
137 * The shared memory allocation routines take a file name.
138 * Depending on system-specific implementation of these
139 * routines, that file may or may not actually be created. We'd
140 * like to store those files in the operating system's designated
141 * temporary directory, which APR can point us to.
142 */
143 rs = apr_temp_dir_get(&tempdir, pconf);
144 if (APR_SUCCESS != rs) {
145 ap_log_error(APLOG_MARK, APLOG_ERR, rs, s, APLOGNO(02992)
146 "Failed to find temporary directory");
147 return HTTP_INTERNAL_SERVER_ERROR;
148 }
149
150 /* Create the shared memory segment */
151
152 /*
153 * Create a unique filename using our pid. This information is
154 * stashed in the global variable so the children inherit it.
155 */
156 shmfilename = apr_psprintf(pconf, "%s/httpd_shm.%ld", tempdir,
157 (long int)getpid());
158
159 /* Now create that segment */
160 rs = apr_shm_create(&exipc_shm, sizeof(exipc_data),
161 (const char *) shmfilename, pconf);
162 if (APR_SUCCESS != rs) {
163 ap_log_error(APLOG_MARK, APLOG_ERR, rs, s, APLOGNO(02993)
164 "Failed to create shared memory segment on file %s",
165 shmfilename);
166 return HTTP_INTERNAL_SERVER_ERROR;
167 }
168
169 /* Created it, now let's zero it out */
170 base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
171 base->counter = 0;
172
173 /* Create global mutex */
174
175 rs = ap_global_mutex_create(&exipc_mutex, NULL, exipc_mutex_type, NULL,
176 s, pconf, 0);
177 if (APR_SUCCESS != rs) {
178 return HTTP_INTERNAL_SERVER_ERROR;
179 }
180
181 /*
182 * Destroy the shm segment when the configuration pool gets destroyed. This
183 * happens on server restarts. The parent will then (above) allocate a new
184 * shm segment that the new children will bind to.
185 */
186 apr_pool_cleanup_register(pconf, NULL, shm_cleanup_wrapper,
187 apr_pool_cleanup_null);
188 return OK;
189}
190
191/*
192 * This routine gets called when a child inits. We use it to attach
193 * to the shared memory segment, and reinitialize the mutex.
194 */
195
196static void exipc_child_init(apr_pool_t *p, server_rec *s)
197{
198 apr_status_t rs;
199
200 /*
201 * Re-open the mutex for the child. Note we're reusing
202 * the mutex pointer global here.
203 */
204 rs = apr_global_mutex_child_init(&exipc_mutex,
205 apr_global_mutex_lockfile(exipc_mutex),
206 p);
207 if (APR_SUCCESS != rs) {
208 ap_log_error(APLOG_MARK, APLOG_CRIT, rs, s, APLOGNO(02994)
209 "Failed to reopen mutex %s in child",
210 exipc_mutex_type);
211 /* There's really nothing else we can do here, since This
212 * routine doesn't return a status. If this ever goes wrong,
213 * it will turn Apache into a fork bomb. Let's hope it never
214 * will.
215 */
216 exit(1); /* Ugly, but what else? */
217 }
218}
219
220/* The sample content handler */
221static int exipc_handler(request_rec *r)
222{
223 int gotlock = 0;
224 int camped;
225 apr_time_t startcamp;
226 apr_int64_t timecamped;
227 apr_status_t rs;
228 exipc_data *base;
229
230 if (strcmp(r->handler, "example_ipc")) {
231 return DECLINED;
232 }
233
234 /*
235 * The main function of the handler, aside from sending the
236 * status page to the client, is to increment the counter in
237 * the shared memory segment. This action needs to be mutexed
238 * out using the global mutex.
239 */
240
241 /*
242 * First, acquire the lock. This code is a lot more involved than
243 * it usually needs to be, because the process based trylock
244 * routine is not implemented on unix platforms. I left it in to
245 * show how it would work if trylock worked, and for situations
246 * and platforms where trylock works.
247 */
248 for (camped = 0, timecamped = 0; camped < MAXCAMP; camped++) {
249 rs = apr_global_mutex_trylock(exipc_mutex);
250 if (APR_STATUS_IS_EBUSY(rs)) {
251 apr_sleep(CAMPOUT);
252 }
253 else if (APR_SUCCESS == rs) {
254 gotlock = 1;
255 break; /* Get out of the loop */
256 }
257 else if (APR_STATUS_IS_ENOTIMPL(rs)) {
258 /* If it's not implemented, just hang in the mutex. */
259 startcamp = apr_time_now();
260 rs = apr_global_mutex_lock(exipc_mutex);
261 timecamped = (apr_int64_t) (apr_time_now() - startcamp);
262 if (APR_SUCCESS == rs) {
263 gotlock = 1;
264 break; /* Out of the loop */
265 }
266 else {
267 /* Some error, log and bail */
268 ap_log_error(APLOG_MARK, APLOG_ERR, rs, r->server, APLOGNO(02995)
269 "Child %ld failed to acquire lock",
270 (long int)getpid());
271 break; /* Out of the loop without having the lock */
272 }
273 }
274 else {
275 /* Some other error, log and bail */
276 ap_log_error(APLOG_MARK, APLOG_ERR, rs, r->server, APLOGNO(02996)
277 "Child %ld failed to try and acquire lock",
278 (long int)getpid());
279 break; /* Out of the loop without having the lock */
280 }
281
282 /*
283 * The only way to get to this point is if the trylock worked
284 * and returned BUSY. So, bump the time and try again
285 */
286 timecamped += CAMPOUT;
287 ap_log_error(APLOG_MARK, APLOG_NOTICE, 0, r->server, APLOGNO(03187)
288 "Child %ld camping out on mutex for %" APR_INT64_T_FMT
289 " microseconds",
290 (long int) getpid(), timecamped);
291 } /* Lock acquisition loop */
292
293 /* Sleep for a millisecond to make it a little harder for
294 * httpd children to acquire the lock.
295 */
296 apr_sleep(SLEEPYTIME);
297
298 r->content_type = "text/html";
299
300 if (!r->header_only) {
301 ap_rputs(HTML_HEADER, r);
302 if (gotlock) {
303 /* Increment the counter */
304 base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
305 base->counter++;
306 /* Send a page with our pid and the new value of the counter. */
307 ap_rprintf(r, "<p>Lock acquired after %ld microseoncds.</p>\n",
308 (long int) timecamped);
309 ap_rputs("<table border=\"1\">\n", r);
310 ap_rprintf(r, "<tr><td>Child pid:</td><td>%d</td></tr>\n",
311 (int) getpid());
312 ap_rprintf(r, "<tr><td>Counter:</td><td>%u</td></tr>\n",
313 (unsigned int)base->counter);
314 ap_rputs("</table>\n", r);
315 }
316 else {
317 /*
318 * Send a page saying that we couldn't get the lock. Don't say
319 * what the counter is, because without the lock the value could
320 * race.
321 */
322 ap_rprintf(r, "<p>Child %d failed to acquire lock "
323 "after camping out for %d microseconds.</p>\n",
324 (int) getpid(), (int) timecamped);
325 }
326 ap_rputs(HTML_FOOTER, r);
327 } /* r->header_only */
328
329 /* Release the lock */
330 if (gotlock)
331 rs = apr_global_mutex_unlock(exipc_mutex);
332 /* Swallowing the result because what are we going to do with it at
333 * this stage?
334 */
335
336 return OK;
337}
338
346
347/* Dispatch list for API hooks */
348AP_DECLARE_MODULE(example_ipc) = {
349 STANDARD20_MODULE_STUFF,
350 NULL, /* create per-dir config structures */
351 NULL, /* merge per-dir config structures */
352 NULL, /* create per-server config structures */
353 NULL, /* merge per-server config structures */
354 NULL, /* table of config file commands */
355 exipc_register_hooks /* register hooks */
356};
ap_config.h
Symbol export macros and hook functions.
apr_strings.h
APR Strings library.
pconf
static apr_pool_t * pconf
Definition event.c:441
ap_hook_post_config
void ap_hook_post_config(ap_HOOK_post_config_t *pf, const char *const *aszPre, const char *const *aszSucc, int nOrder)
Definition config.c:105
AP_DECLARE_MODULE
#define AP_DECLARE_MODULE(foo)
Definition http_config.h:464
base
ap_conf_vector_t * base
Definition http_config.h:1125
ap_hook_handler
void ap_hook_handler(ap_HOOK_handler_t *pf, const char *const *aszPre, const char *const *aszSucc, int nOrder)
Definition config.c:170
ap_hook_pre_config
void ap_hook_pre_config(ap_HOOK_pre_config_t *pf, const char *const *aszPre, const char *const *aszSucc, int nOrder)
Definition config.c:91
r
request_rec * r
Definition http_config.h:1168
ap_hook_child_init
void ap_hook_child_init(ap_HOOK_child_init_t *pf, const char *const *aszPre, const char *const *aszSucc, int nOrder)
Definition config.c:167
DECLINED
#define DECLINED
Definition httpd.h:457
OK
#define OK
Definition httpd.h:456
AP_SQ_MS_CREATE_PRE_CONFIG
#define AP_SQ_MS_CREATE_PRE_CONFIG
Definition http_core.h:1047
ap_state_query
int ap_state_query(int query_code)
Definition core.c:5378
AP_SQ_MAIN_STATE
#define AP_SQ_MAIN_STATE
Definition http_core.h:1030
APLOGNO
#define APLOGNO(n)
Definition http_log.h:117
APLOG_NOTICE
#define APLOG_NOTICE
Definition http_log.h:69
APLOG_ERR
#define APLOG_ERR
Definition http_log.h:67
ap_log_error
#define ap_log_error
Definition http_log.h:370
APLOG_MARK
#define APLOG_MARK
Definition http_log.h:283
APLOG_CRIT
#define APLOG_CRIT
Definition http_log.h:66
ap_global_mutex_create
apr_status_t ap_global_mutex_create(apr_global_mutex_t **mutex, const char **name, const char *type, const char *instance_id, server_rec *server, apr_pool_t *pool, apr_int32_t options)
Definition util_mutex.c:407
ap_mutex_register
apr_status_t ap_mutex_register(apr_pool_t *pconf, const char *type, const char *default_dir, apr_lockmech_e default_mech, apr_int32_t options)
Definition util_mutex.c:254
ap_rprintf
int ap_rprintf(request_rec *r, const char *fmt,...) __attribute__((format(printf
ap_rputs
static APR_INLINE int ap_rputs(const char *str, request_rec *r)
Definition http_protocol.h:487
APR_STATUS_IS_EBUSY
#define APR_STATUS_IS_EBUSY(s)
Definition apr_errno.h:628
APR_STATUS_IS_ENOTIMPL
#define APR_STATUS_IS_ENOTIMPL(s)
Definition apr_errno.h:615
APR_HOOK_MIDDLE
#define APR_HOOK_MIDDLE
Definition apr_hooks.h:303
rs
apr_redis_server_t * rs
Definition apr_redis.h:205
HTTP_INTERNAL_SERVER_ERROR
#define HTTP_INTERNAL_SERVER_ERROR
Definition httpd.h:535
STANDARD20_MODULE_STUFF
#define STANDARD20_MODULE_STUFF
Definition http_config.h:486
size
apr_size_t size
Definition apr_allocator.h:115
APR_SUCCESS
#define APR_SUCCESS
Definition apr_errno.h:225
apr_status_t
int apr_status_t
Definition apr_errno.h:44
APR_LOCK_DEFAULT
@ APR_LOCK_DEFAULT
Definition apr_proc_mutex.h:52
s
const char * s
Definition apr_strings.h:95
apr_time_t
apr_int64_t apr_time_t
Definition apr_time.h:45
http_config.h
Apache Configuration.
http_core.h
CORE HTTP Daemon.
http_log.h
Apache Logging library.
http_protocol.h
HTTP protocol handling.
httpd.h
HTTP Daemon routines.
p
apr_pool_t * p
Definition md_event.c:32
exipc_handler
static int exipc_handler(request_rec *r)
Definition mod_example_ipc.c:221
exipc_shm
apr_shm_t * exipc_shm
Definition mod_example_ipc.c:77
shmfilename
char * shmfilename
Definition mod_example_ipc.c:78
CAMPOUT
#define CAMPOUT
Definition mod_example_ipc.c:71
HTML_HEADER
#define HTML_HEADER
Definition mod_example_ipc.c:66
exipc_register_hooks
static void exipc_register_hooks(apr_pool_t *p)
Definition mod_example_ipc.c:339
HTML_FOOTER
#define HTML_FOOTER
Definition mod_example_ipc.c:68
exipc_child_init
static void exipc_child_init(apr_pool_t *p, server_rec *s)
Definition mod_example_ipc.c:196
SLEEPYTIME
#define SLEEPYTIME
Definition mod_example_ipc.c:75
MAXCAMP
#define MAXCAMP
Definition mod_example_ipc.c:73
exipc_mutex
apr_global_mutex_t * exipc_mutex
Definition mod_example_ipc.c:79
exipc_pre_config
static int exipc_pre_config(apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp)
Definition mod_example_ipc.c:107
exipc_mutex_type
static const char * exipc_mutex_type
Definition mod_example_ipc.c:80
exipc_post_config
static int exipc_post_config(apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)
Definition mod_example_ipc.c:119
shm_cleanup_wrapper
static apr_status_t shm_cleanup_wrapper(void *unused)
Definition mod_example_ipc.c:94
NULL
return NULL
Definition mod_so.c:359
apr_global_mutex_t
Definition apr_arch_global_mutex.h:23
apr_pool_t
Definition apr_pools.c:562
apr_shm_t
Definition apr_arch_shm.h:61
exipc_data
Definition mod_example_ipc.c:83
exipc_data::counter
apr_uint64_t counter
Definition mod_example_ipc.c:84
request_rec
A structure that represents the current request.
Definition httpd.h:845
request_rec::content_type
const char * content_type
Definition httpd.h:992
request_rec::header_only
int header_only
Definition httpd.h:875
request_rec::handler
const char * handler
Definition httpd.h:994
request_rec::server
server_rec * server
Definition httpd.h:851
server_rec
A structure to store information for each virtual server.
Definition httpd.h:1322
util_mutex.h
Apache Mutex support library.
Generated by doxygen 1.9.8