glib/garcbox.c

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