glib/grcbox.c

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