contrib/subversion/subversion/include/private/svn_mutex.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_mutex.h
  24  * @brief Strutures and functions for mutual exclusion
  25  */
  26
  27 #ifndef SVN_MUTEX_H
  28 #define SVN_MUTEX_H
  29
  30 #include <apr_thread_mutex.h>
  31
  32 #include "svn_error.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /**
  39  * This is a simple wrapper around @c apr_thread_mutex_t and will be a
  40  * valid identifier even if APR does not support threading.
  41  */
  42 #if APR_HAS_THREADS
  43
  44 /** A mutex for synchronization between threads. It may be NULL, in
  45  * which case no synchronization will take place. The latter is useful
  46  * when implementing some functionality with optional synchronization.
  47  */
  48 typedef apr_thread_mutex_t svn_mutex__t;
  49
  50 #else
  51
  52 /** Dummy definition. The content will never be actually accessed.
  53  */
  54 typedef void svn_mutex__t;
  55
  56 #endif
  57
  58 /** Initialize the @a *mutex. If @a mutex_required is TRUE, the mutex will
  59  * actually be created with a lifetime defined by @a result_pool. Otherwise,
  60  * the pointer will be set to @c NULL and svn_mutex__lock() as well as
  61  * svn_mutex__unlock() will be no-ops.
  62  *
  63  * If threading is not supported by APR, this function is a no-op.
  64  */
  65 svn_error_t *
  66 svn_mutex__init(svn_mutex__t **mutex,
  67                 svn_boolean_t mutex_required,
  68                 apr_pool_t *result_pool);
  69
  70 /** Acquire the @a mutex, if that has been enabled in svn_mutex__init().
  71  * Make sure to call svn_mutex__unlock() some time later in the same
  72  * thread to release the mutex again. Recursive locking are not supported.
  73  *
  74  * @note You should use #SVN_MUTEX__WITH_LOCK instead of explicit lock
  75  * aquisition and release.
  76  */
  77 svn_error_t *
  78 svn_mutex__lock(svn_mutex__t *mutex);
  79
  80 /** Release the @a mutex, previously acquired using svn_mutex__lock()
  81  * that has been enabled in svn_mutex__init().
  82  *
  83  * Since this is often used as part of the calling function's exit
  84  * sequence, we accept that function's current return code in @a err.
  85  * If it is not #SVN_NO_ERROR, it will be used as the return value -
  86  * irrespective of the possible internal failures during unlock. If @a err
  87  * is #SVN_NO_ERROR, internal failures of this function will be
  88  * reported in the return value.
  89  *
  90  * @note You should use #SVN_MUTEX__WITH_LOCK instead of explicit lock
  91  * aquisition and release.
  92  */
  93 svn_error_t *
  94 svn_mutex__unlock(svn_mutex__t *mutex,
  95                   svn_error_t *err);
  96
  97 /** Aquires the @a mutex, executes the expression @a expr and finally
  98  * releases the @a mutex. If any of these steps fail, the function using
  99  * this macro will return an #svn_error_t. This macro guarantees that
 100  * the @a mutex will always be unlocked again if it got locked successfully
 101  * by the first step.
 102  *
 103  * @note Prefer using this macro instead of explicit lock aquisition and
 104  * release.
 105  */
 106 #define SVN_MUTEX__WITH_LOCK(mutex, expr)               \
 107 do {                                                    \
 108   svn_mutex__t *svn_mutex__m = (mutex);                 \
 109   SVN_ERR(svn_mutex__lock(svn_mutex__m));               \
 110   SVN_ERR(svn_mutex__unlock(svn_mutex__m, (expr)));     \
 111 } while (0)
 112
 113 #ifdef __cplusplus
 114 }
 115 #endif /* __cplusplus */
 116
 117 #endif /* SVN_MUTEX_H */