glib/garcbox.c

   1 /* garcbox.c: Atomically reference counted data
   2  *
   3  * Copyright 2018  Emmanuele Bassi
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #include "config.h"
  22
  23 #include "grcboxprivate.h"
  24
  25 #include "gmessages.h"
  26 #include "grefcount.h"
  27
  28 #ifdef ENABLE_VALGRIND
  29 #include "valgrind.h"
  30 #endif
  31
  32 #include "glib_trace.h"
  33
  34 #include <string.h>
  35
  36 #define G_ARC_BOX(p)            (GArcBox *) (((char *) (p)) - G_ARC_BOX_SIZE)
  37
  38 /**
  39  * SECTION:arcbox
  40  * @Title: Atomically reference counted data
  41  * @Short_description: Allocated memory with atomic reference counting semantics
  42  *
  43  * An "atomically reference counted box", or "ArcBox", is an opaque wrapper
  44  * data type that is guaranteed to be as big as the size of a given data type,
  45  * and which augments the given data type with thread safe reference counting
  46  * semantics for its memory management.
  47  *
  48  * ArcBox is useful if you have a plain old data type, like a structure
  49  * typically placed on the stack, and you wish to provide additional API
  50  * to use it on the heap; or if you want to implement a new type to be
  51  * passed around by reference without necessarily implementing copy/free
  52  * semantics or your own reference counting.
  53  *
  54  * The typical use is:
  55  *
  56  * |[<!-- language="C" -->
  57  * typedef struct {
  58  *   char *name;
  59  *   char *address;
  60  *   char *city;
  61  *   char *state;
  62  *   int age;
  63  * } Person;
  64  *
  65  * Person *
  66  * person_new (void)
  67  * {
  68  *   return g_atomic_rc_box_new0 (Person);
  69  * }
  70  * ]|
  71  *
  72  * Every time you wish to acquire a reference on the memory, you should
  73  * call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference
  74  * you should call g_atomic_rc_box_release():
  75  *
  76  * |[<!-- language="C" -->
  77  * // Add a Person to the Database; the Database acquires ownership
  78  * // of the Person instance
  79  * void
  80  * add_person_to_database (Database *db, Person *p)
  81  * {
  82  *   db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p));
  83  * }
  84  *
  85  * // Removes a Person from the Database; the reference acquired by
  86  * // add_person_to_database() is released here
  87  * void
  88  * remove_person_from_database (Database *db, Person *p)
  89  * {
  90  *   db->persons = g_list_remove (db->persons, p);
  91  *   g_atomic_rc_box_release (p);
  92  * }
  93  * ]|
  94  *
  95  * If you have additional memory allocated inside the structure, you can
  96  * use g_atomic_rc_box_release_full(), which takes a function pointer, which
  97  * will be called if the reference released was the last:
  98  *
  99  * |[<!-- language="C" -->
 100  * void
 101  * person_clear (Person *p)
 102  * {
 103  *   g_free (p->name);
 104  *   g_free (p->address);
 105  *   g_free (p->city);
 106  *   g_free (p->state);
 107  * }
 108  *
 109  * void
 110  * remove_person_from_database (Database *db, Person *p)
 111  * {
 112  *   db->persons = g_list_remove (db->persons, p);
 113  *   g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear);
 114  * }
 115  * ]|
 116  *
 117  * If you wish to transfer the ownership of a reference counted data
 118  * type without increasing the reference count, you can use g_steal_pointer():
 119  *
 120  * |[<!-- language="C" -->
 121  *   Person *p = g_atomic_rc_box_new (Person);
 122  *
 123  *   fill_person_details (p);
 124  *
 125  *   add_person_to_database (db, g_steal_pointer (&p));
 126  * ]|
 127  *
 128  * ## Thread safety
 129  *
 130  * The reference counting operations on data allocated using g_atomic_rc_box_alloc(),
 131  * g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus
 132  * can be safely be performed by different threads. It is important to note that
 133  * only the reference acquisition and release are atomic; changes to the content
 134  * of the data are your responsibility.
 135  *
 136  * ## Automatic pointer clean up
 137  *
 138  * If you want to add g_autoptr() support to your plain old data type through
 139  * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
 140  * g_atomic_rc_box_release():
 141  *
 142  * |[<!-- language="C" -->
 143  * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release)
 144  * ]|
 145  *
 146  * If you need to clear the contents of the data, you will need to use an
 147  * ancillary function that calls g_rc_box_release_full():
 148  *
 149  * |[<!-- language="C" -->
 150  * static void
 151  * my_data_struct_release (MyDataStruct *data)
 152  * {
 153  *   // my_data_struct_clear() is defined elsewhere
 154  *   g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
 155  * }
 156  *
 157  * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
 158  * ]|
 159  *
 160  * Since: 2.58
 161  */
 162
 163 /**
 164  * g_atomic_rc_box_alloc:
 165  * @block_size: the size of the allocation, must be greater than 0
 166  *
 167  * Allocates @block_size bytes of memory, and adds atomic
 168  * reference counting semantics to it.
 169  *
 170  * The data will be freed when its reference count drops to
 171  * zero.
 172  *
 173  * The allocated data is guaranteed to be suitably aligned for any
 174  * built-in type.
 175  *
 176  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
 177  *
 178  * Since: 2.58
 179  */
 180 gpointer
 181 g_atomic_rc_box_alloc (gsize block_size)
 182 {
 183   g_return_val_if_fail (block_size > 0, NULL);
 184
 185   return g_rc_box_alloc_full (block_size, STRUCT_ALIGNMENT, TRUE, FALSE);
 186 }
 187
 188 /**
 189  * g_atomic_rc_box_alloc0:
 190  * @block_size: the size of the allocation, must be greater than 0
 191  *
 192  * Allocates @block_size bytes of memory, and adds atomic
 193  * reference counting semantics to it.
 194  *
 195  * The contents of the returned data is set to zero.
 196  *
 197  * The data will be freed when its reference count drops to
 198  * zero.
 199  *
 200  * The allocated data is guaranteed to be suitably aligned for any
 201  * built-in type.
 202  *
 203  * Returns: (transfer full) (not nullable): a pointer to the allocated memory
 204  *
 205  * Since: 2.58
 206  */
 207 gpointer
 208 g_atomic_rc_box_alloc0 (gsize block_size)
 209 {
 210   g_return_val_if_fail (block_size > 0, NULL);
 211
 212   return g_rc_box_alloc_full (block_size, STRUCT_ALIGNMENT, TRUE, TRUE);
 213 }
 214
 215 /**
 216  * g_atomic_rc_box_new:
 217  * @type: the type to allocate, typically a structure name
 218  *
 219  * A convenience macro to allocate atomically reference counted
 220  * data with the size of the given @type.
 221  *
 222  * This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and
 223  * casts the returned pointer to a pointer of the given @type,
 224  * avoiding a type cast in the source code.
 225  *
 226  * Returns: (transfer full) (not nullable): a pointer to the allocated
 227  *   memory, cast to a pointer for the given @type
 228  *
 229  * Since: 2.58
 230  */
 231
 232 /**
 233  * g_atomic_rc_box_new0:
 234  * @type: the type to allocate, typically a structure name
 235  *
 236  * A convenience macro to allocate atomically reference counted
 237  * data with the size of the given @type, and set its contents
 238  * to zero.
 239  *
 240  * This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and
 241  * casts the returned pointer to a pointer of the given @type,
 242  * avoiding a type cast in the source code.
 243  *
 244  * Returns: (transfer full) (not nullable): a pointer to the allocated
 245  *   memory, cast to a pointer for the given @type
 246  *
 247  * Since: 2.58
 248  */
 249
 250 /**
 251  * g_atomic_rc_box_dup:
 252  * @block_size: the number of bytes to copy, must be greater than 0
 253  * @mem_block: (not nullable): the memory to copy
 254  *
 255  * Allocates a new block of data with atomic reference counting
 256  * semantics, and copies @block_size bytes of @mem_block
 257  * into it.
 258  *
 259  * Returns: (transfer full) (not nullable): a pointer to the allocated
 260  *   memory
 261  *
 262  * Since: 2.58
 263  */
 264 gpointer
 265 (g_atomic_rc_box_dup) (gsize         block_size,
 266                        gconstpointer mem_block)
 267 {
 268   gpointer res;
 269
 270   g_return_val_if_fail (block_size > 0, NULL);
 271   g_return_val_if_fail (mem_block != NULL, NULL);
 272
 273   res = g_rc_box_alloc_full (block_size, STRUCT_ALIGNMENT, TRUE, FALSE);
 274   memcpy (res, mem_block, block_size);
 275
 276   return res;
 277 }
 278
 279 /**
 280  * g_atomic_rc_box_acquire:
 281  * @mem_block: (not nullable): a pointer to reference counted data
 282  *
 283  * Atomically acquires a reference on the data pointed by @mem_block.
 284  *
 285  * Returns: (transfer full) (not nullable): a pointer to the data,
 286  *   with its reference count increased
 287  *
 288  * Since: 2.58
 289  */
 290 gpointer
 291 (g_atomic_rc_box_acquire) (gpointer mem_block)
 292 {
 293   GArcBox *real_box = G_ARC_BOX (mem_block);
 294
 295   g_return_val_if_fail (mem_block != NULL, NULL);
 296 #ifndef G_DISABLE_ASSERT
 297   g_return_val_if_fail (real_box->magic == G_BOX_MAGIC, NULL);
 298 #endif
 299
 300   g_atomic_ref_count_inc (&real_box->ref_count);
 301
 302   TRACE (GLIB_RCBOX_ACQUIRE (mem_block, 1));
 303
 304   return mem_block;
 305 }
 306
 307 /**
 308  * g_atomic_rc_box_release:
 309  * @mem_block: (transfer full) (not nullable): a pointer to reference counted data
 310  *
 311  * Atomically releases a reference on the data pointed by @mem_block.
 312  *
 313  * If the reference was the last one, it will free the
 314  * resources allocated for @mem_block.
 315  *
 316  * Since: 2.58
 317  */
 318 void
 319 g_atomic_rc_box_release (gpointer mem_block)
 320 {
 321   g_atomic_rc_box_release_full (mem_block, NULL);
 322 }
 323
 324 /**
 325  * g_atomic_rc_box_release_full:
 326  * @mem_block: (transfer full) (not nullable): a pointer to reference counted data
 327  * @clear_func: (not nullable): a function to call when clearing the data
 328  *
 329  * Atomically releases a reference on the data pointed by @mem_block.
 330  *
 331  * If the reference was the last one, it will call @clear_func
 332  * to clear the contents of @mem_block, and then will free the
 333  * resources allocated for @mem_block.
 334  *
 335  * Since: 2.58
 336  */
 337 void
 338 g_atomic_rc_box_release_full (gpointer       mem_block,
 339                               GDestroyNotify clear_func)
 340 {
 341   GArcBox *real_box = G_ARC_BOX (mem_block);
 342
 343   g_return_if_fail (mem_block != NULL);
 344 #ifndef G_DISABLE_ASSERT
 345   g_return_if_fail (real_box->magic == G_BOX_MAGIC);
 346 #endif
 347
 348   if (g_atomic_ref_count_dec (&real_box->ref_count))
 349     {
 350       char *real_mem = (char *) real_box - real_box->private_offset;
 351
 352       TRACE (GLIB_RCBOX_RELEASE (mem_block, 1));
 353
 354       if (clear_func != NULL)
 355         clear_func (mem_block);
 356
 357       TRACE (GLIB_RCBOX_FREE (mem_block));
 358       g_free (real_mem);
 359     }
 360 }
 361
 362 /**
 363  * g_atomic_rc_box_get_size:
 364  * @mem_block: (not nullable): a pointer to reference counted data
 365  *
 366  * Retrieves the size of the reference counted data pointed by @mem_block.
 367  *
 368  * Returns: the size of the data, in bytes
 369  *
 370  * Since: 2.58
 371  */
 372 gsize
 373 g_atomic_rc_box_get_size (gpointer mem_block)
 374 {
 375   GArcBox *real_box = G_ARC_BOX (mem_block);
 376
 377   g_return_val_if_fail (mem_block != NULL, 0);
 378 #ifndef G_DISABLE_ASSERT
 379   g_return_val_if_fail (real_box->magic == G_BOX_MAGIC, 0);
 380 #endif
 381
 382   return real_box->mem_size;
 383 }