contrib/subversion/subversion/include/private/svn_named_atomic.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_named_atomics.h
  24  * @brief Structures and functions for machine-wide named atomics.
  25  *        These atomics store 64 bit signed integer values and provide
  26  *        a number of basic operations on them. Instead of an address,
  27  *        these atomics are identified by strings / names.  We also support
  28  *        namespaces - mainly to separate debug from production data.
  29  */
  30
  31 #ifndef SVN_NAMED_ATOMICS_H
  32 #define SVN_NAMED_ATOMICS_H
  33
  34 #include "svn_error.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif /* __cplusplus */
  39
  40 /** An opaque structure that represents a namespace, i.e. a container
  41  * for named atomics.
  42  */
  43 typedef struct svn_atomic_namespace__t svn_atomic_namespace__t;
  44
  45 /** An opaque structure that represents a named, system-wide visible
  46  * 64 bit integer with atomic access routines.
  47  */
  48 typedef struct svn_named_atomic__t svn_named_atomic__t;
  49
  50 /** Maximum length of the name of any atomic (excluding the terminal NUL).
  51  */
  52 #define SVN_NAMED_ATOMIC__MAX_NAME_LENGTH 30
  53
  54 /** Returns #FALSE when named atomics are not available to our process
  55  * and svn_atomic_namespace__create is likely to fail.
  56  *
  57  * @note The actual check will be performed only once and later
  58  * changes in process privileges will not reflect in the outcome of future
  59  * calls to this function.
  60  */
  61 svn_boolean_t
  62 svn_named_atomic__is_supported(void);
  63
  64 /** Returns #TRUE on platforms that don't need expensive synchronization
  65  * objects to serialize access to named atomics. If this returns #FALSE,
  66  * reading from or modifying a #svn_named_atomic__t may be as expensive
  67  * as a file system operation.
  68  */
  69 svn_boolean_t
  70 svn_named_atomic__is_efficient(void);
  71
  72 /** Create a namespace (i.e. access object) with the given @a name and
  73  * return it in @a *ns.
  74  *
  75  * Multiple access objects with the same name may be created.  They access
  76  * the same shared memory region but have independent lifetimes.
  77  *
  78  * The access object will be allocated in @a result_pool and atomics gotten
  79  * from this object will become invalid when the pool is being cleared.
  80  */
  81 svn_error_t *
  82 svn_atomic_namespace__create(svn_atomic_namespace__t **ns,
  83                              const char *name,
  84                              apr_pool_t *result_pool);
  85
  86 /** Removes persistent data structures (files in particular) that got
  87  * created for the namespace given by @a name.  Use @a pool for temporary
  88  * allocations.
  89  *
  90  * @note You must not call this while the respective namespace is still
  91  * in use. Calling this multiple times for the same namespace is safe.
  92  */
  93 svn_error_t *
  94 svn_atomic_namespace__cleanup(const char *name,
  95                               apr_pool_t *pool);
  96
  97 /** Find the atomic with the specified @a name in namespace @a ns and
  98  * return it in @a *atomic.  If no object with that name can be found, the
  99  * behavior depends on @a auto_create.  If it is @c FALSE, @a *atomic will
 100  * be set to @c NULL. Otherwise, a new atomic will be created, its value
 101  * set to 0 and the access structure be returned in @a *atomic.
 102  *
 103  * Note that @a name must not exceed #SVN_NAMED_ATOMIC__MAX_NAME_LENGTH
 104  * characters and an error will be returned if the specified name is longer
 105  * than supported.
 106  *
 107  * @note The lifetime of the atomic object is bound to the lifetime
 108  * of the @a ns object, i.e. the pool the latter was created in.
 109  * The data in the namespace persists as long as at least one process
 110  * holds an #svn_atomic_namespace__t object corresponding to it.
 111  */
 112 svn_error_t *
 113 svn_named_atomic__get(svn_named_atomic__t **atomic,
 114                       svn_atomic_namespace__t *ns,
 115                       const char *name,
 116                       svn_boolean_t auto_create);
 117
 118 /** Read the @a atomic and return its current @a *value.
 119  * An error will be returned if @a atomic is @c NULL.
 120  */
 121 svn_error_t *
 122 svn_named_atomic__read(apr_int64_t *value,
 123                        svn_named_atomic__t *atomic);
 124
 125 /** Set the data in @a atomic to @a new_value and return its old content
 126  * in @a *old_value.  @a old_value may be NULL.
 127  *
 128  * An error will be returned if @a atomic is @c NULL.
 129  */
 130 svn_error_t *
 131 svn_named_atomic__write(apr_int64_t *old_value,
 132                         apr_int64_t new_value,
 133                         svn_named_atomic__t *atomic);
 134
 135 /** Add @a delta to the data in @a atomic and return its new value in
 136  * @a *new_value.  @a new_value may be null.
 137  *
 138  * An error will be returned if @a atomic is @c NULL.
 139  */
 140 svn_error_t *
 141 svn_named_atomic__add(apr_int64_t *new_value,
 142                       apr_int64_t delta,
 143                       svn_named_atomic__t *atomic);
 144
 145 /** If the current data in @a atomic equals @a comperand, set it to
 146  * @a new_value.  Return the initial value in @a *old_value.
 147  * @a old_value may be NULL.
 148  *
 149  * An error will be returned if @a atomic is @c NULL.
 150  */
 151 svn_error_t *
 152 svn_named_atomic__cmpxchg(apr_int64_t *old_value,
 153                           apr_int64_t new_value,
 154                           apr_int64_t comperand,
 155                           svn_named_atomic__t *atomic);
 156
 157
 158 #ifdef __cplusplus
 159 }
 160 #endif /* __cplusplus */
 161
 162 #endif /* SVN_NAMED_ATOMICS_H */