granicus.if.org Git - apache/blob - modules/examples/mod_example_ipc.c

   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_log.h"
  54 #include "http_protocol.h"
  55 #include "ap_config.h"
  56
  57 #if !defined(OS2) && !defined(WIN32) && !defined(NETWARE)
  58 #include "unixd.h"
  59 #define MOD_EXIPC_SET_MUTEX_PERMS /* XXX Apache should define something */
  60 #endif
  61
  62 #if APR_HAVE_SYS_TYPES_H
  63 #include <sys/types.h>
  64 #endif
  65 #if APR_HAVE_UNISTD_H
  66 #include <unistd.h>
  67 #endif
  68
  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"
  72
  73 /* Number of microseconds to camp out on the mutex */
  74 #define CAMPOUT 10
  75 /* Maximum number of times we camp out before giving up */
  76 #define MAXCAMP 10
  77 /* Number of microseconds the handler sits on the lock once acquired. */
  78 #define SLEEPYTIME 1000
  79
  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 */
  84
  85 /* Data structure for shared memory block */
  86 typedef struct exipc_data {
  87     apr_uint64_t counter;
  88     /* More fields if necessary */
  89 } exipc_data;
  90
  91 /*
  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.
  96  */
  97 static apr_status_t shm_cleanup_wrapper(void *unused) {
  98     if (exipc_shm)
  99         return apr_shm_destroy(exipc_shm);
 100     return OK;
 101 }
 102
 103
 104 /*
 105  * This routine is called in the parent, so we'll set up the shared
 106  * memory segment and mutex here.
 107  */
 108
 109 static int exipc_post_config(apr_pool_t *pconf, apr_pool_t *plog,
 110                              apr_pool_t *ptemp, server_rec *s)
 111 {
 112     void *data; /* These two help ensure that we only init once. */
 113     const char *userdata_key;
 114     apr_status_t rs;
 115     exipc_data *base;
 116     const char *tempdir;
 117
 118
 119     /*
 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.
 125      *
 126      * The key needs to be unique for the entire web server, so put
 127      * the module name in it.
 128      */
 129     userdata_key = "example_ipc_init_module";
 130     apr_pool_userdata_get(&data, userdata_key, s->process->pool);
 131     if (!data) {
 132         /*
 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
 135          * key and return.
 136          */
 137         apr_pool_userdata_set((const void *) 1, userdata_key,
 138                               apr_pool_cleanup_null, s->process->pool);
 139         return OK;
 140     } /* Kilroy was here */
 141
 142     /*
 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.
 148      */
 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;
 154     }
 155
 156     /* Create the shared memory segment */
 157
 158     /*
 159      * Create a unique filename using our pid. This information is
 160      * stashed in the global variable so the children inherit it.
 161      */
 162     shmfilename = apr_psprintf(pconf, "%s/httpd_shm.%ld", tempdir,
 163                                (long int)getpid());
 164
 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",
 171                      shmfilename);
 172         return HTTP_INTERNAL_SERVER_ERROR;
 173     }
 174
 175     /* Created it, now let's zero it out */
 176     base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
 177     base->counter = 0;
 178
 179     /* Create global mutex */
 180
 181     /*
 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.
 185      */
 186     mutexfilename = apr_psprintf(pconf, "%s/httpd_mutex.%ld", tempdir,
 187                                  (long int) getpid());
 188
 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",
 194                      mutexfilename);
 195         return HTTP_INTERNAL_SERVER_ERROR;
 196     }
 197
 198     /*
 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
 203      * it.
 204      */
 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;
 212     }
 213 #endif /* MOD_EXIPC_SET_MUTEX_PERMS */
 214
 215     /*
 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.
 219      */
 220     apr_pool_cleanup_register(pconf, NULL, shm_cleanup_wrapper,
 221                               apr_pool_cleanup_null);
 222     return OK;
 223 }
 224
 225 /*
 226  * This routine gets called when a child inits. We use it to attach
 227  * to the shared memory segment, and reinitialize the mutex.
 228  */
 229
 230 static void exipc_child_init(apr_pool_t *p, server_rec *s)
 231 {
 232     apr_status_t rs;
 233
 234     /*
 235      * Re-open the mutex for the child. Note we're reusing
 236      * the mutex pointer global here.
 237      */
 238     rs = apr_global_mutex_child_init(&exipc_mutex,
 239                                      (const char *) mutexfilename,
 240                                      p);
 241     if (APR_SUCCESS != rs) {
 242         ap_log_error(APLOG_MARK, APLOG_CRIT, rs, s,
 243                      "Failed to reopen mutex on file %s",
 244                      shmfilename);
 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
 248          * will.
 249          */
 250         exit(1); /* Ugly, but what else? */
 251     }
 252 }
 253
 254 /* The sample content handler */
 255 static int exipc_handler(request_rec *r)
 256 {
 257     int gotlock = 0;
 258     int camped;
 259     apr_time_t startcamp;
 260     apr_int64_t timecamped;
 261     apr_status_t rs;
 262     exipc_data *base;
 263
 264     if (strcmp(r->handler, "example_ipc")) {
 265         return DECLINED;
 266     }
 267
 268     /*
 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.
 273      */
 274
 275     /*
 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.
 281      */
 282     for (camped = 0, timecamped = 0; camped < MAXCAMP; camped++) {
 283         rs = apr_global_mutex_trylock(exipc_mutex);
 284         if (APR_STATUS_IS_EBUSY(rs)) {
 285             apr_sleep(CAMPOUT);
 286         } else if (APR_SUCCESS == rs) {
 287             gotlock = 1;
 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) {
 295                 gotlock = 1;
 296                 break; /* Out of the loop */
 297             } else {
 298                 /* Some error, log and bail */
 299                 ap_log_error(APLOG_MARK, APLOG_ERR, rs, r->server,
 300                              "Child %ld failed to acquire lock",
 301                              (long int)getpid());
 302                 break; /* Out of the loop without having the lock */
 303             }
 304         } else {
 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",
 308                          (long int)getpid());
 309             break; /* Out of the loop without having the lock */
 310
 311         }
 312         /*
 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
 315          */
 316         timecamped += CAMPOUT;
 317         ap_log_error(APLOG_MARK, APLOG_NOERRNO | APLOG_NOTICE,
 318                      0, r->server, "Child %ld camping out on mutex for %" APR_INT64_T_FMT
 319                      " microseconds",
 320                      (long int) getpid(), timecamped);
 321     } /* Lock acquisition loop */
 322
 323     /* Sleep for a millisecond to make it a little harder for
 324      * httpd children to acquire the lock.
 325      */
 326     apr_sleep(SLEEPYTIME);
 327
 328     r->content_type = "text/html";
 329
 330     if (!r->header_only) {
 331         ap_rputs(HTML_HEADER, r);
 332         if (gotlock) {
 333             /* Increment the counter */
 334             base = (exipc_data *)apr_shm_baseaddr_get(exipc_shm);
 335             base->counter++;
 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",
 341                        (int) getpid());
 342             ap_rprintf(r, "<tr><td>Counter:</td><td>%u</td></tr>\n",
 343                        (unsigned int)base->counter);
 344             ap_rputs("</table>\n", r);
 345         } else {
 346             /*
 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
 349              * race.
 350              */
 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);
 354         }
 355         ap_rputs(HTML_FOOTER, r);
 356     } /* r->header_only */
 357
 358     /* Release the lock */
 359     if (gotlock)
 360         rs = apr_global_mutex_unlock(exipc_mutex);
 361     /* Swallowing the result because what are we going to do with it at
 362      * this stage?
 363      */
 364
 365     return OK;
 366 }
 367
 368 static void exipc_register_hooks(apr_pool_t *p)
 369 {
 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);
 373 }
 374
 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                      */
 384 };
 385