Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 11 - C API Reference Guide, Part II
Data Mutex Locking

Apache provides a cross-platform API for implementing data mutex locking. This is a mechanism implemented on most platforms to provide serialization when multiple concurrent threads need access to global data. The API was introduced with the Win32 port of Apache and will be adapted to future multithreaded versions of Apache for other platforms. While there is no need to implement data access serialization under multiprocess versions of Apache, this API will still work in such environments and is recommended for portability.³

mutex *ap_create_mutex (char *name)

This function is used to allocate a mutex structure, which is required to implement runtime locking. This structure is normally a global variable, which is created during the module initialization phase.

static mutex *my_mutex = NULL;
static void my_module_init(server_rec *s, pool *p)
{
   if (!my_mutex) {
       my_mutex = ap_create_mutex(NULL);
   }
}

int ap_acquire_mutex (mutex *mutex_id)

The ap_acquire_mutex() function will acquire a lock. If a lock has already been acquired by another thread, it will block until it is released by the other thread.

int ap_release_mutex (mutex *mutex_id)

After locked data access is complete, the ap_release_mutex() function must be called so other threads are able to acquire locks.

static int my_handler(request_rec *r)
{
   ...
   (void)ap_acquire_mutex(my_mutex);
   /* read or modify some global data */
   (void)ap_release_mutex(my_mutex);
}

void ap_destroy_mutex (mutex *mutex_id)

This function will release any resources associated with a mutex structure that was created with ap_create_mutex().

ap_destroy_mutex(my_mutex);
my_mutex = NULL;

Footnotes

3 Under multiprocess versions of Apache, such as 1.3.x under Unix, using the mutex API does not introduce any overhead, as each function is simply defined as a no-op macro.