home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277223_apr_proc_mutex.h < prev    next >
C/C++ Source or Header  |  2004-02-13  |  6KB  |  166 lines
  1. /* Copyright 2000-2004 The Apache Software Foundation
  2.  *
  3.  * Licensed under the Apache License, Version 2.0 (the "License");
  4.  * you may not use this file except in compliance with the License.
  5.  * You may obtain a copy of the License at
  6.  *
  7.  *     http://www.apache.org/licenses/LICENSE-2.0
  8.  *
  9.  * Unless required by applicable law or agreed to in writing, software
  10.  * distributed under the License is distributed on an "AS IS" BASIS,
  11.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12.  * See the License for the specific language governing permissions and
  13.  * limitations under the License.
  14.  */
  15.  
  16. #ifndef APR_PROC_MUTEX_H
  17. #define APR_PROC_MUTEX_H
  18.  
  19. /**
  20.  * @file apr_proc_mutex.h
  21.  * @brief APR Process Locking Routines
  22.  */
  23.  
  24. #include "apr.h"
  25. #include "apr_pools.h"
  26. #include "apr_errno.h"
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif /* __cplusplus */
  31.  
  32. /**
  33.  * @defgroup apr_proc_mutex Process Locking Routines
  34.  * @ingroup APR 
  35.  * @{
  36.  */
  37.  
  38. /** 
  39.  * Enumerated potential types for APR process locking methods
  40.  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
  41.  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
  42.  */
  43. typedef enum {
  44.     APR_LOCK_FCNTL,         /**< fcntl() */
  45.     APR_LOCK_FLOCK,         /**< flock() */
  46.     APR_LOCK_SYSVSEM,       /**< System V Semaphores */
  47.     APR_LOCK_PROC_PTHREAD,  /**< POSIX pthread process-based locking */
  48.     APR_LOCK_POSIXSEM,      /**< POSIX semaphore process-based locking */
  49.     APR_LOCK_DEFAULT        /**< Use the default process lock */
  50. } apr_lockmech_e;
  51.  
  52. /** Opaque structure representing a process mutex. */
  53. typedef struct apr_proc_mutex_t apr_proc_mutex_t;
  54.  
  55. /*   Function definitions */
  56.  
  57. /**
  58.  * Create and initialize a mutex that can be used to synchronize processes.
  59.  * @param mutex the memory address where the newly created mutex will be
  60.  *        stored.
  61.  * @param fname A file name to use if the lock mechanism requires one.  This
  62.  *        argument should always be provided.  The lock code itself will
  63.  *        determine if it should be used.
  64.  * @param mech The mechanism to use for the interprocess lock, if any; one of
  65.  * <PRE>
  66.  *            APR_LOCK_FCNTL
  67.  *            APR_LOCK_FLOCK
  68.  *            APR_LOCK_SYSVSEM
  69.  *            APR_LOCK_POSIXSEM
  70.  *            APR_LOCK_PROC_PTHREAD
  71.  *            APR_LOCK_DEFAULT     pick the default mechanism for the platform
  72.  * </PRE>
  73.  * @param pool the pool from which to allocate the mutex.
  74.  * @see apr_lockmech_e
  75.  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
  76.  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
  77.  */
  78. APR_DECLARE(apr_status_t) apr_proc_mutex_create(apr_proc_mutex_t **mutex,
  79.                                                 const char *fname,
  80.                                                 apr_lockmech_e mech,
  81.                                                 apr_pool_t *pool);
  82.  
  83. /**
  84.  * Re-open a mutex in a child process.
  85.  * @param mutex The newly re-opened mutex structure.
  86.  * @param fname A file name to use if the mutex mechanism requires one.  This
  87.  *              argument should always be provided.  The mutex code itself will
  88.  *              determine if it should be used.  This filename should be the 
  89.  *              same one that was passed to apr_proc_mutex_create().
  90.  * @param pool The pool to operate on.
  91.  * @remark This function must be called to maintain portability, even
  92.  *         if the underlying lock mechanism does not require it.
  93.  */
  94. APR_DECLARE(apr_status_t) apr_proc_mutex_child_init(apr_proc_mutex_t **mutex,
  95.                                                     const char *fname,
  96.                                                     apr_pool_t *pool);
  97.  
  98. /**
  99.  * Acquire the lock for the given mutex. If the mutex is already locked,
  100.  * the current thread will be put to sleep until the lock becomes available.
  101.  * @param mutex the mutex on which to acquire the lock.
  102.  */
  103. APR_DECLARE(apr_status_t) apr_proc_mutex_lock(apr_proc_mutex_t *mutex);
  104.  
  105. /**
  106.  * Attempt to acquire the lock for the given mutex. If the mutex has already
  107.  * been acquired, the call returns immediately with APR_EBUSY. Note: it
  108.  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
  109.  * if the return value was APR_EBUSY, for portability reasons.
  110.  * @param mutex the mutex on which to attempt the lock acquiring.
  111.  */
  112. APR_DECLARE(apr_status_t) apr_proc_mutex_trylock(apr_proc_mutex_t *mutex);
  113.  
  114. /**
  115.  * Release the lock for the given mutex.
  116.  * @param mutex the mutex from which to release the lock.
  117.  */
  118. APR_DECLARE(apr_status_t) apr_proc_mutex_unlock(apr_proc_mutex_t *mutex);
  119.  
  120. /**
  121.  * Destroy the mutex and free the memory associated with the lock.
  122.  * @param mutex the mutex to destroy.
  123.  */
  124. APR_DECLARE(apr_status_t) apr_proc_mutex_destroy(apr_proc_mutex_t *mutex);
  125.  
  126. /**
  127.  * Destroy the mutex and free the memory associated with the lock.
  128.  * @param mutex the mutex to destroy.
  129.  * @note This function is generally used to kill a cleanup on an already
  130.  *       created mutex
  131.  */
  132. APR_DECLARE(apr_status_t) apr_proc_mutex_cleanup(void *mutex);
  133.  
  134. /**
  135.  * Return the name of the lockfile for the mutex, or NULL
  136.  * if the mutex doesn't use a lock file
  137.  */
  138.  
  139. APR_DECLARE(const char *) apr_proc_mutex_lockfile(apr_proc_mutex_t *mutex);
  140.  
  141. /**
  142.  * Display the name of the mutex, as it relates to the actual method used.
  143.  * This matches the valid options for Apache's AcceptMutex directive
  144.  * @param mutex the name of the mutex
  145.  */
  146. APR_DECLARE(const char *) apr_proc_mutex_name(apr_proc_mutex_t *mutex);
  147.  
  148. /**
  149.  * Display the name of the default mutex: APR_LOCK_DEFAULT
  150.  */
  151. APR_DECLARE(const char *) apr_proc_mutex_defname(void);
  152.  
  153. /**
  154.  * Get the pool used by this proc_mutex.
  155.  * @return apr_pool_t the pool
  156.  */
  157. APR_POOL_DECLARE_ACCESSOR(proc_mutex);
  158.  
  159. /** @} */
  160.  
  161. #ifdef __cplusplus
  162. }
  163. #endif
  164.  
  165. #endif  /* ! APR_PROC_MUTEX_H */
  166.