glib/grefcount.c

   1 /* grefcount.c: Reference counting
   2  *
   3  * Copyright 2018  Emmanuele Bassi
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 /**
  20  * SECTION:refcount
  21  * @Title: Reference counting
  22  * @Short_description: Reference counting types and functions
  23  *
  24  * Reference counting is a garbage collection mechanism that is based on
  25  * assigning a counter to a data type, or any memory area; the counter is
  26  * increased whenever a new reference to that data type is acquired, and
  27  * decreased whenever the reference is released. Once the last reference
  28  * is released, the resources associated to that data type are freed.
  29  *
  30  * GLib uses reference counting in many of its data types, and provides
  31  * the #grefcount and #gatomicrefcount types to implement safe and atomic
  32  * reference counting semantics in new data types.
  33  *
  34  * It is important to note that #grefcount and #gatomicrefcount should be
  35  * considered completely opaque types; you should always use the provided
  36  * API to increase and decrease the counters, and you should never check
  37  * their content directly, or compare their content with other values.
  38  *
  39  * Since: 2.58
  40  */
  41
  42 #include "config.h"
  43
  44 #include "grefcount.h"
  45
  46 #include "gatomic.h"
  47 #include "gmessages.h"
  48
  49 /**
  50  * grefcount:
  51  *
  52  * A type for implementing non-atomic reference count semantics.
  53  *
  54  * Use g_ref_count_init() to initialize it; g_ref_count_inc() to
  55  * increase the counter, and g_ref_count_dec() to decrease it.
  56  *
  57  * It is safe to use #grefcount only if you're expecting to operate
  58  * on the reference counter from a single thread. It is entirely up
  59  * to you to ensure that all reference count changes happen in the
  60  * same thread.
  61  *
  62  * See also: #gatomicrefcount
  63  *
  64  * Since: 2.58
  65  */
  66
  67 /**
  68  * gatomicrefcount:
  69  *
  70  * A type for implementing atomic reference count semantics.
  71  *
  72  * Use g_atomic_ref_count_init() to initialize it; g_atomic_ref_count_inc()
  73  * to increase the counter, and g_atomic_ref_count_dec() to decrease it.
  74  *
  75  * It is safe to use #gatomicrefcount if you're expecting to operate on the
  76  * reference counter from multiple threads.
  77  *
  78  * See also: #grefcount
  79  *
  80  * Since: 2.58
  81  */
  82
  83 /**
  84  * g_ref_count_init:
  85  * @rc: the address of a reference count variable
  86  *
  87  * Initializes a reference count variable.
  88  *
  89  * Since: 2.58
  90  */
  91 void
  92 (g_ref_count_init) (grefcount *rc)
  93 {
  94   g_return_if_fail (rc != NULL);
  95
  96   /* Non-atomic refcounting is implemented using the negative range
  97    * of signed integers:
  98    *
  99    * G_MININT                 Z¯< 0 > Z⁺                G_MAXINT
 100    * |----------------------------|----------------------------|
 101    *
 102    * Acquiring a reference moves us towards MININT, and releasing a
 103    * reference moves us towards 0.
 104    */
 105   *rc = -1;
 106 }
 107
 108 /**
 109  * g_ref_count_inc:
 110  * @rc: the address of a reference count variable
 111  *
 112  * Increases the reference count.
 113  *
 114  * Since: 2.58
 115  */
 116 void
 117 (g_ref_count_inc) (grefcount *rc)
 118 {
 119   grefcount rrc;
 120
 121   g_return_if_fail (rc != NULL);
 122
 123   rrc = *rc;
 124
 125   g_return_if_fail (rrc < 0);
 126
 127   /* Check for saturation */
 128   if (rrc == G_MININT)
 129     {
 130       g_critical ("Reference count %p has reached saturation", rc);
 131       return;
 132     }
 133
 134   rrc -= 1;
 135
 136   *rc = rrc;
 137 }
 138
 139 /**
 140  * g_ref_count_dec:
 141  * @rc: the address of a reference count variable
 142  *
 143  * Decreases the reference count.
 144  *
 145  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
 146  *
 147  * Since: 2.58
 148  */
 149 gboolean
 150 (g_ref_count_dec) (grefcount *rc)
 151 {
 152   grefcount rrc;
 153
 154   g_return_val_if_fail (rc != NULL, FALSE);
 155
 156   rrc = *rc;
 157
 158   g_return_val_if_fail (rrc < 0, FALSE);
 159
 160   rrc += 1;
 161   if (rrc == 0)
 162     return TRUE;
 163
 164   *rc = rrc;
 165
 166   return FALSE;
 167 }
 168
 169 /**
 170  * g_ref_count_compare:
 171  * @rc: the address of a reference count variable
 172  * @val: the value to compare
 173  *
 174  * Compares the current value of @rc with @val.
 175  *
 176  * Returns: %TRUE if the reference count is the same
 177  *   as the given value
 178  *
 179  * Since: 2.58
 180  */
 181 gboolean
 182 (g_ref_count_compare) (grefcount *rc,
 183                        gint       val)
 184 {
 185   grefcount rrc;
 186
 187   g_return_val_if_fail (rc != NULL, FALSE);
 188   g_return_val_if_fail (val >= 0, FALSE);
 189
 190   rrc = *rc;
 191
 192   if (val == G_MAXINT)
 193     return rrc == G_MININT;
 194
 195   return rrc == -val;
 196 }
 197
 198 /**
 199  * g_atomic_ref_count_init:
 200  * @arc: the address of an atomic reference count variable
 201  *
 202  * Atomically initializes a reference count variable.
 203  *
 204  * Since: 2.58
 205  */
 206 void
 207 (g_atomic_ref_count_init) (gatomicrefcount *arc)
 208 {
 209   g_return_if_fail (arc != NULL);
 210
 211   /* Atomic refcounting is implemented using the positive range
 212    * of signed integers:
 213    *
 214    * G_MININT                 Z¯< 0 > Z⁺                G_MAXINT
 215    * |----------------------------|----------------------------|
 216    *
 217    * Acquiring a reference moves us towards MAXINT, and releasing a
 218    * reference moves us towards 0.
 219    */
 220   g_atomic_int_set (arc, 1);
 221 }
 222
 223 /**
 224  * g_atomic_ref_count_inc:
 225  * @arc: the address of an atomic reference count variable
 226  *
 227  * Atomically increases the reference count.
 228  *
 229  * Since: 2.58
 230  */
 231 void
 232 (g_atomic_ref_count_inc) (gatomicrefcount *arc)
 233 {
 234   g_return_if_fail (arc != NULL);
 235   g_return_if_fail (g_atomic_int_get (arc) > 0);
 236
 237   if (g_atomic_int_get (arc) == G_MAXINT)
 238     {
 239       g_critical ("Reference count has reached saturation");
 240       return;
 241     }
 242
 243   g_atomic_int_inc (arc);
 244 }
 245
 246 /**
 247  * g_atomic_ref_count_dec:
 248  * @arc: the address of an atomic reference count variable
 249  *
 250  * Atomically decreases the reference count.
 251  *
 252  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
 253  *
 254  * Since: 2.58
 255  */
 256 gboolean
 257 (g_atomic_ref_count_dec) (gatomicrefcount *arc)
 258 {
 259   g_return_val_if_fail (arc != NULL, FALSE);
 260   g_return_val_if_fail (g_atomic_int_get (arc) > 0, FALSE);
 261
 262   return g_atomic_int_dec_and_test (arc);
 263 }
 264
 265 /**
 266  * g_atomic_ref_count_compare:
 267  * @arc: the address of an atomic reference count variable
 268  * @val: the value to compare
 269  *
 270  * Atomically compares the current value of @arc with @val.
 271  *
 272  * Returns: %TRUE if the reference count is the same
 273  *   as the given value
 274  *
 275  * Since: 2.58
 276  */
 277 gboolean
 278 (g_atomic_ref_count_compare) (gatomicrefcount *arc,
 279                               gint             val)
 280 {
 281   g_return_val_if_fail (arc != NULL, FALSE);
 282   g_return_val_if_fail (val >= 0, FALSE);
 283
 284   return g_atomic_int_get (arc) == val;
 285 }