glib/grcbox.c

   1 /* grcbox.c: 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 /**
  34  * SECTION:rcbox
  35  * @Title: Reference counted data
  36  * @Short_description: Allocated memory with reference counting semantics
  37  *
  38  * A "reference counted box", or "RcBox", is an opaque wrapper data type
  39  * that is guaranteed to be as big as the size of a given data type, and
  40  * which augments the given data type with reference counting semantics
  41  * for its memory management.
  42  *
  43  * RcBox is useful if you have a plain old data type, like a structure
  44  * typically placed on the stack, and you wish to provide additional API
  45  * to use it on the heap, without necessarily implementing copy/free
  46  * semantics, or your own reference counting.
  47  *
  48  * The typical use is:
  49  *
  50  * |[<!-- language="C" -->
  51  * typedef struct {
  52  *   float x, y;
  53  * } Point;
  54  *
  55  * Point *
  56  * point_new (float x, float y)
  57  * {
  58  *   Point *res = g_rc_box_new (Point);
  59  *
  60  *   res->x = x;
  61  *   res->y = y;
  62  *
  63  *   return res;
  64  * }
  65  * ]|
  66  *
  67  * Every time you wish to acquire a reference on the memory, you should
  68  * call g_rc_box_acquire(); similarly, when you wish to release a reference
  69  * you should call g_rc_box_release():
  70  *
  71  * |[<!-- language="C" -->
  72  * Point *
  73  * point_ref (Point *p)
  74  * {
  75  *   return g_rc_box_acquire (p);
  76  * }
  77  *
  78  * void
  79  * point_unref (Point *p)
  80  * {
  81  *   g_rc_box_release (p);
  82  * }
  83  * ]|
  84  *
  85  * If you have additional memory allocated inside the structure, you can
  86  * use g_rc_box_release_full(), which takes a function pointer, which
  87  * will be called if the reference released was the last:
  88  *
  89  * |[<!-- language="C" -->
  90  * typedef struct {
  91  *   char *name;
  92  *   char *address;
  93  *   char *city;
  94  *   char *state;
  95  *   int age;
  96  * } Person;
  97  *
  98  * void
  99  * person_clear (Person *p)
 100  * {
 101  *   g_free (p->name);
 102  *   g_free (p->address);
 103  *   g_free (p->city);
 104  *   g_free (p->state);
 105  * }
 106  *
 107  * void
 108  * person_unref (Person *p)
 109  * {
 110  *   g_rc_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_rc_box_new (Person);
 119  *
 120  *   fill_person_details (p);
 121  *
 122  *   add_person_to_database (db, g_steal_pointer (&p));
 123  * ]|
 124  *
 125  * The reference counting operations on data allocated using g_rc_box_alloc(),
 126  * g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's
 127  * responsibility to ensure that references are acquired are released on the
 128  * same thread.
 129  *
 130  * Since: 2.58.
 131  */
 132
 133 #define G_RC_BOX(p)             (GRcBox *) (((char *) (p)) - G_RC_BOX_SIZE)
 134
 135 /* We use the same alignment as GTypeInstance and GNU libc's malloc */
 136 #define STRUCT_ALIGNMENT        (2 * sizeof (gsize))
 137 #define ALIGN_STRUCT(offset)    ((offset + (STRUCT_ALIGNMENT - 1)) & -STRUCT_ALIGNMENT)
 138
 139 gpointer
 140 g_rc_box_alloc_full (gsize    block_size,
 141                      gboolean atomic,
 142                      gboolean clear)
 143 {
 144   /* sizeof GArcBox == sizeof GRcBox */
 145   gsize private_size = G_ARC_BOX_SIZE;
 146   gsize real_size = private_size + block_size;
 147   char *allocated;
 148
 149 #ifdef ENABLE_VALGRIND
 150   if (RUNNING_ON_VALGRIND)
 151     {
 152       /* When running under Valgrind we massage the memory allocation
 153        * to include a pointer at the tail end of the block; the pointer
 154        * is then set to the start of the block. This trick allows
 155        * Valgrind to keep track of the over-allocation and not be
 156        * confused when passing the pointer around
 157        */
 158       private_size += ALIGN_STRUCT (1);
 159
 160       if (clear)
 161         allocated = g_malloc0 (real_size + sizeof (gpointer));
 162       else
 163         allocated = g_malloc (real_size + sizeof (gpointer));
 164
 165       *(gpointer *) (allocated + private_size + block_size) = allocated + ALIGN_STRUCT (1);
 166
 167       VALGRIND_MALLOCLIKE_BLOCK (allocated + private_size, block_size + sizeof (gpointer), 0, TRUE);
 168       VALGRIND_MALLOCLIKE_BLOCK (allocated + ALIGN_STRUCT (1), private_size - ALIGN_STRUCT (1), 0, TRUE);
 169     }
 170   else
 171 #endif /* ENABLE_VALGRIND */
 172     {
 173       if (clear)
 174         allocated = g_malloc0 (real_size);
 175       else
 176         allocated = g_malloc (real_size);
 177     }
 178
 179   if (atomic)
 180     {
 181       GArcBox *real_box = (GArcBox *) allocated;
 182       real_box->mem_size = block_size;
 183 #ifndef G_DISABLE_ASSERT
 184       real_box->magic = G_BOX_MAGIC;
 185 #endif
 186       g_atomic_ref_count_init (&real_box->ref_count);
 187     }
 188   else
 189     {
 190       GRcBox *real_box = (GRcBox *) allocated;
 191       real_box->mem_size = block_size;
 192 #ifndef G_DISABLE_ASSERT
 193       real_box->magic = G_BOX_MAGIC;
 194 #endif
 195       g_ref_count_init (&real_box->ref_count);
 196     }
 197
 198   return allocated + private_size;
 199 }
 200
 201 /**
 202  * g_rc_box_alloc:
 203  * @block_size: the size of the allocation
 204  *
 205  * Allocates @block_size bytes of memory, and adds reference
 206  * counting semantics to it.
 207  *
 208  * The data will be freed when its reference count drops to
 209  * zero.
 210  *
 211  * Returns: a pointer to the allocated memory
 212  *
 213  * Since: 2.58
 214  */
 215 gpointer
 216 g_rc_box_alloc (gsize block_size)
 217 {
 218   g_return_val_if_fail (block_size > 0, NULL);
 219
 220   return g_rc_box_alloc_full (block_size, FALSE, FALSE);
 221 }
 222
 223 /**
 224  * g_rc_box_alloc0:
 225  * @block_size: the size of the allocation
 226  *
 227  * Allocates @block_size bytes of memory, and adds reference
 228  * counting semantics to it.
 229  *
 230  * The contents of the returned data is set to 0's.
 231  *
 232  * The data will be freed when its reference count drops to
 233  * zero.
 234  *
 235  * Returns: a pointer to the allocated memory
 236  *
 237  * Since: 2.58
 238  */
 239 gpointer
 240 g_rc_box_alloc0 (gsize block_size)
 241 {
 242   g_return_val_if_fail (block_size > 0, NULL);
 243
 244   return g_rc_box_alloc_full (block_size, FALSE, TRUE);
 245 }
 246
 247 /**
 248  * g_rc_box_new:
 249  * @type: the type to allocate, typically a structure name
 250  *
 251  * A convenience macro to allocate reference counted data with
 252  * the size of the given @type.
 253  *
 254  * This macro calls g_rc_box_alloc() with `sizeof (@type)` and
 255  * casts the returned pointer to a pointer of the given @type,
 256  * avoiding a type cast in the source code.
 257  *
 258  * This macro cannot return %NULL, as the minimum allocation
 259  * size from `sizeof (@type)` is 1 byte.
 260  *
 261  * Returns: (not nullable): a pointer to the allocated memory,
 262  *   cast to a pointer for the given @type
 263  *
 264  * Since: 2.58
 265  */
 266
 267 /**
 268  * g_rc_box_new0:
 269  * @type: the type to allocate, typically a structure name
 270  *
 271  * A convenience macro to allocate reference counted data with
 272  * the size of the given @type, and set its contents to 0.
 273  *
 274  * This macro calls g_rc_box_alloc0() with `sizeof (@type)` and
 275  * casts the returned pointer to a pointer of the given @type,
 276  * avoiding a type cast in the source code.
 277  *
 278  * This macro cannot return %NULL, as the minimum allocation
 279  * size from `sizeof (@type)` is 1 byte.
 280  *
 281  * Returns: (not nullable): a pointer to the allocated memory,
 282  *   cast to a pointer for the given @type
 283  *
 284  * Since: 2.58
 285  */
 286
 287 /**
 288  * g_rc_box_dup:
 289  * @block_size: the number of bytes to copy
 290  * @mem_block: (not nullable): the memory to copy
 291  *
 292  * Allocates a new block of data with reference counting
 293  * semantics, and copies @block_size bytes of @mem_block
 294  * into it.
 295  *
 296  * Returns: (not nullable): a pointer to the allocated memory
 297  *
 298  * Since: 2.58
 299  */
 300 gpointer
 301 (g_rc_box_dup) (gsize         block_size,
 302                 gconstpointer mem_block)
 303 {
 304   gpointer res;
 305
 306   g_return_val_if_fail (block_size > 0, NULL);
 307   g_return_val_if_fail (mem_block != NULL, NULL);
 308
 309   res = g_rc_box_alloc_full (block_size, FALSE, FALSE);
 310   memcpy (res, mem_block, block_size);
 311
 312   return res;
 313 }
 314
 315 /**
 316  * g_rc_box_acquire:
 317  * @mem_block: (not nullable): a pointer to reference counted data
 318  *
 319  * Acquires a reference on the data pointed by @mem_block.
 320  *
 321  * Returns: (not nullabl): a pointer to the data, with its reference
 322  *   count increased
 323  *
 324  * Since: 2.58
 325  */
 326 gpointer
 327 (g_rc_box_acquire) (gpointer mem_block)
 328 {
 329   GRcBox *real_box = G_RC_BOX (mem_block);
 330
 331   g_return_val_if_fail (mem_block != NULL, NULL);
 332 #ifndef G_DISABLE_ASSERT
 333   g_return_val_if_fail (real_box->magic == G_BOX_MAGIC, NULL);
 334 #endif
 335
 336   g_ref_count_inc (&real_box->ref_count);
 337
 338   return mem_block;
 339 }
 340
 341 /**
 342  * g_rc_box_release:
 343  * @mem_block: (not nullable): a pointer to reference counted data
 344  *
 345  * Releases a reference on the data pointed by @mem_block.
 346  *
 347  * If the reference was the last one, it will free the
 348  * resources allocated for @mem_block.
 349  *
 350  * Since: 2.58
 351  */
 352 void
 353 g_rc_box_release (gpointer mem_block)
 354 {
 355   GRcBox *real_box = G_RC_BOX (mem_block);
 356
 357   g_return_if_fail (mem_block != NULL);
 358 #ifndef G_DISABLE_ASSERT
 359   g_return_if_fail (real_box->magic == G_BOX_MAGIC);
 360 #endif
 361
 362   if (g_ref_count_dec (&real_box->ref_count))
 363     g_free (real_box);
 364 }
 365
 366 /**
 367  * g_rc_box_release_full:
 368  * @mem_block: (not nullabl): a pointer to reference counted data
 369  * @clear_func: (not nullable): a function to call when clearing the data
 370  *
 371  * Releases a reference on the data pointed by @mem_block.
 372  *
 373  * If the reference was the last one, it will call @clear_func
 374  * to clear the contents of @mem_block, and then will free the
 375  * resources allocated for @mem_block.
 376  *
 377  * Since: 2.58
 378  */
 379 void
 380 g_rc_box_release_full (gpointer       mem_block,
 381                        GDestroyNotify clear_func)
 382 {
 383   GRcBox *real_box = G_RC_BOX (mem_block);
 384
 385   g_return_if_fail (mem_block != NULL);
 386   g_return_if_fail (clear_func != NULL);
 387 #ifndef G_DISABLE_ASSERT
 388   g_return_if_fail (real_box->magic == G_BOX_MAGIC);
 389 #endif
 390
 391   if (g_ref_count_dec (&real_box->ref_count))
 392     {
 393       clear_func (mem_block);
 394       g_free (real_box);
 395     }
 396 }