glib/gbytes.c

   1 /*
   2  * Copyright © 2009, 2010 Codethink Limited
   3  * Copyright © 2011 Collabora Ltd.
   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  * Author: Ryan Lortie <desrt@desrt.ca>
  19  *         Stef Walter <stefw@collabora.co.uk>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gbytes.h"
  25
  26 #include <glib/garray.h>
  27 #include <glib/gstrfuncs.h>
  28 #include <glib/gatomic.h>
  29 #include <glib/gslice.h>
  30 #include <glib/gtestutils.h>
  31 #include <glib/gmem.h>
  32 #include <glib/gmessages.h>
  33
  34 #include <string.h>
  35
  36 /**
  37  * GBytes:
  38  *
  39  * A simple refcounted data type representing an immutable sequence of zero or
  40  * more bytes from an unspecified origin.
  41  *
  42  * The purpose of a #GBytes is to keep the memory region that it holds
  43  * alive for as long as anyone holds a reference to the bytes.  When
  44  * the last reference count is dropped, the memory is released. Multiple
  45  * unrelated callers can use byte data in the #GBytes without coordinating
  46  * their activities, resting assured that the byte data will not change or
  47  * move while they hold a reference.
  48  *
  49  * A #GBytes can come from many different origins that may have
  50  * different procedures for freeing the memory region.  Examples are
  51  * memory from g_malloc(), from memory slices, from a #GMappedFile or
  52  * memory from other allocators.
  53  *
  54  * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
  55  * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
  56  * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
  57  * function to g_tree_new().
  58  *
  59  * The data pointed to by this bytes must not be modified. For a mutable
  60  * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
  61  * mutable array for a #GBytes sequence. To create an immutable #GBytes from
  62  * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
  63  *
  64  * Since: 2.32
  65  **/
  66
  67 /* Keep in sync with glib/tests/bytes.c */
  68 struct _GBytes
  69 {
  70   gconstpointer data;  /* may be NULL iff (size == 0) */
  71   gsize size;  /* may be 0 */
  72   gint ref_count;
  73   GDestroyNotify free_func;
  74   gpointer user_data;
  75 };
  76
  77 /**
  78  * g_bytes_new:
  79  * @data: (transfer none) (array length=size) (element-type guint8) (nullable):
  80  *        the data to be used for the bytes
  81  * @size: the size of @data
  82  *
  83  * Creates a new #GBytes from @data.
  84  *
  85  * @data is copied. If @size is 0, @data may be %NULL.
  86  *
  87  * Returns: (transfer full): a new #GBytes
  88  *
  89  * Since: 2.32
  90  */
  91 GBytes *
  92 g_bytes_new (gconstpointer data,
  93              gsize         size)
  94 {
  95   g_return_val_if_fail (data != NULL || size == 0, NULL);
  96
  97   return g_bytes_new_take (g_memdup (data, size), size);
  98 }
  99
 100 /**
 101  * g_bytes_new_take:
 102  * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
 103  *        the data to be used for the bytes
 104  * @size: the size of @data
 105  *
 106  * Creates a new #GBytes from @data.
 107  *
 108  * After this call, @data belongs to the bytes and may no longer be
 109  * modified by the caller.  g_free() will be called on @data when the
 110  * bytes is no longer in use. Because of this @data must have been created by
 111  * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
 112  * functions that wrap these calls (such as g_new(), g_strdup(), etc).
 113  *
 114  * For creating #GBytes with memory from other allocators, see
 115  * g_bytes_new_with_free_func().
 116  *
 117  * @data may be %NULL if @size is 0.
 118  *
 119  * Returns: (transfer full): a new #GBytes
 120  *
 121  * Since: 2.32
 122  */
 123 GBytes *
 124 g_bytes_new_take (gpointer data,
 125                   gsize    size)
 126 {
 127   return g_bytes_new_with_free_func (data, size, g_free, data);
 128 }
 129
 130
 131 /**
 132  * g_bytes_new_static: (skip)
 133  * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
 134  *        the data to be used for the bytes
 135  * @size: the size of @data
 136  *
 137  * Creates a new #GBytes from static data.
 138  *
 139  * @data must be static (ie: never modified or freed). It may be %NULL if @size
 140  * is 0.
 141  *
 142  * Returns: (transfer full): a new #GBytes
 143  *
 144  * Since: 2.32
 145  */
 146 GBytes *
 147 g_bytes_new_static (gconstpointer data,
 148                     gsize         size)
 149 {
 150   return g_bytes_new_with_free_func (data, size, NULL, NULL);
 151 }
 152
 153 /**
 154  * g_bytes_new_with_free_func: (skip)
 155  * @data: (array length=size) (element-type guint8) (nullable):
 156  *        the data to be used for the bytes
 157  * @size: the size of @data
 158  * @free_func: the function to call to release the data
 159  * @user_data: data to pass to @free_func
 160  *
 161  * Creates a #GBytes from @data.
 162  *
 163  * When the last reference is dropped, @free_func will be called with the
 164  * @user_data argument.
 165  *
 166  * @data must not be modified after this call is made until @free_func has
 167  * been called to indicate that the bytes is no longer in use.
 168  *
 169  * @data may be %NULL if @size is 0.
 170  *
 171  * Returns: (transfer full): a new #GBytes
 172  *
 173  * Since: 2.32
 174  */
 175 GBytes *
 176 g_bytes_new_with_free_func (gconstpointer  data,
 177                             gsize          size,
 178                             GDestroyNotify free_func,
 179                             gpointer       user_data)
 180 {
 181   GBytes *bytes;
 182
 183   g_return_val_if_fail (data != NULL || size == 0, NULL);
 184
 185   bytes = g_slice_new (GBytes);
 186   bytes->data = data;
 187   bytes->size = size;
 188   bytes->free_func = free_func;
 189   bytes->user_data = user_data;
 190   bytes->ref_count = 1;
 191
 192   return (GBytes *)bytes;
 193 }
 194
 195 /**
 196  * g_bytes_new_from_bytes:
 197  * @bytes: a #GBytes
 198  * @offset: offset which subsection starts at
 199  * @length: length of subsection
 200  *
 201  * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
 202  * @length may not be longer than the size of @bytes.
 203  *
 204  * A reference to @bytes will be held by the newly created #GBytes until
 205  * the byte data is no longer needed.
 206  *
 207  * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
 208  * @bytes will be returned with the reference count incremented by 1. If @bytes
 209  * is a slice of another #GBytes, then the resulting #GBytes will reference
 210  * the same #GBytes instead of @bytes. This allows consumers to simplify the
 211  * usage of #GBytes when asynchronously writing to streams.
 212  *
 213  * Returns: (transfer full): a new #GBytes
 214  *
 215  * Since: 2.32
 216  */
 217 GBytes *
 218 g_bytes_new_from_bytes (GBytes  *bytes,
 219                         gsize    offset,
 220                         gsize    length)
 221 {
 222   gchar *base;
 223
 224   /* Note that length may be 0. */
 225   g_return_val_if_fail (bytes != NULL, NULL);
 226   g_return_val_if_fail (offset <= bytes->size, NULL);
 227   g_return_val_if_fail (offset + length <= bytes->size, NULL);
 228
 229   /* Avoid an extra GBytes if all bytes were requested */
 230   if (offset == 0 && length == bytes->size)
 231     return g_bytes_ref (bytes);
 232
 233   base = (gchar *)bytes->data + offset;
 234
 235   /* Avoid referencing intermediate GBytes. In practice, this should
 236    * only loop once.
 237    */
 238   while (bytes->free_func == (gpointer)g_bytes_unref)
 239     bytes = bytes->user_data;
 240
 241   g_return_val_if_fail (bytes != NULL, NULL);
 242   g_return_val_if_fail (base >= (gchar *)bytes->data, NULL);
 243   g_return_val_if_fail (base <= (gchar *)bytes->data + bytes->size, NULL);
 244   g_return_val_if_fail (base + length <= (gchar *)bytes->data + bytes->size, NULL);
 245
 246   return g_bytes_new_with_free_func (base, length,
 247                                      (GDestroyNotify)g_bytes_unref, g_bytes_ref (bytes));
 248 }
 249
 250 /**
 251  * g_bytes_get_data:
 252  * @bytes: a #GBytes
 253  * @size: (out) (optional): location to return size of byte data
 254  *
 255  * Get the byte data in the #GBytes. This data should not be modified.
 256  *
 257  * This function will always return the same pointer for a given #GBytes.
 258  *
 259  * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
 260  * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
 261  * not be returned if @size is non-zero.
 262  *
 263  * Returns: (transfer none) (array length=size) (element-type guint8) (nullable):
 264  *          a pointer to the byte data, or %NULL
 265  *
 266  * Since: 2.32
 267  */
 268 gconstpointer
 269 g_bytes_get_data (GBytes *bytes,
 270                   gsize *size)
 271 {
 272   g_return_val_if_fail (bytes != NULL, NULL);
 273   if (size)
 274     *size = bytes->size;
 275   return bytes->data;
 276 }
 277
 278 /**
 279  * g_bytes_get_size:
 280  * @bytes: a #GBytes
 281  *
 282  * Get the size of the byte data in the #GBytes.
 283  *
 284  * This function will always return the same value for a given #GBytes.
 285  *
 286  * Returns: the size
 287  *
 288  * Since: 2.32
 289  */
 290 gsize
 291 g_bytes_get_size (GBytes *bytes)
 292 {
 293   g_return_val_if_fail (bytes != NULL, 0);
 294   return bytes->size;
 295 }
 296
 297
 298 /**
 299  * g_bytes_ref:
 300  * @bytes: a #GBytes
 301  *
 302  * Increase the reference count on @bytes.
 303  *
 304  * Returns: the #GBytes
 305  *
 306  * Since: 2.32
 307  */
 308 GBytes *
 309 g_bytes_ref (GBytes *bytes)
 310 {
 311   g_return_val_if_fail (bytes != NULL, NULL);
 312
 313   g_atomic_int_inc (&bytes->ref_count);
 314
 315   return bytes;
 316 }
 317
 318 /**
 319  * g_bytes_unref:
 320  * @bytes: (nullable): a #GBytes
 321  *
 322  * Releases a reference on @bytes.  This may result in the bytes being
 323  * freed. If @bytes is %NULL, it will return immediately.
 324  *
 325  * Since: 2.32
 326  */
 327 void
 328 g_bytes_unref (GBytes *bytes)
 329 {
 330   if (bytes == NULL)
 331     return;
 332
 333   if (g_atomic_int_dec_and_test (&bytes->ref_count))
 334     {
 335       if (bytes->free_func != NULL)
 336         bytes->free_func (bytes->user_data);
 337       g_slice_free (GBytes, bytes);
 338     }
 339 }
 340
 341 /**
 342  * g_bytes_equal:
 343  * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
 344  * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
 345  *
 346  * Compares the two #GBytes values being pointed to and returns
 347  * %TRUE if they are equal.
 348  *
 349  * This function can be passed to g_hash_table_new() as the @key_equal_func
 350  * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
 351  *
 352  * Returns: %TRUE if the two keys match.
 353  *
 354  * Since: 2.32
 355  */
 356 gboolean
 357 g_bytes_equal (gconstpointer bytes1,
 358                gconstpointer bytes2)
 359 {
 360   const GBytes *b1 = bytes1;
 361   const GBytes *b2 = bytes2;
 362
 363   g_return_val_if_fail (bytes1 != NULL, FALSE);
 364   g_return_val_if_fail (bytes2 != NULL, FALSE);
 365
 366   return b1->size == b2->size &&
 367          memcmp (b1->data, b2->data, b1->size) == 0;
 368 }
 369
 370 /**
 371  * g_bytes_hash:
 372  * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
 373  *
 374  * Creates an integer hash code for the byte data in the #GBytes.
 375  *
 376  * This function can be passed to g_hash_table_new() as the @key_hash_func
 377  * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
 378  *
 379  * Returns: a hash value corresponding to the key.
 380  *
 381  * Since: 2.32
 382  */
 383 guint
 384 g_bytes_hash (gconstpointer bytes)
 385 {
 386   const GBytes *a = bytes;
 387   const signed char *p, *e;
 388   guint32 h = 5381;
 389
 390   g_return_val_if_fail (bytes != NULL, 0);
 391
 392   for (p = (signed char *)a->data, e = (signed char *)a->data + a->size; p != e; p++)
 393     h = (h << 5) + h + *p;
 394
 395   return h;
 396 }
 397
 398 /**
 399  * g_bytes_compare:
 400  * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
 401  * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
 402  *
 403  * Compares the two #GBytes values.
 404  *
 405  * This function can be used to sort GBytes instances in lexographical order.
 406  *
 407  * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
 408  *          greater, and zero if bytes2 is equal to bytes1
 409  *
 410  * Since: 2.32
 411  */
 412 gint
 413 g_bytes_compare (gconstpointer bytes1,
 414                  gconstpointer bytes2)
 415 {
 416   const GBytes *b1 = bytes1;
 417   const GBytes *b2 = bytes2;
 418   gint ret;
 419
 420   g_return_val_if_fail (bytes1 != NULL, 0);
 421   g_return_val_if_fail (bytes2 != NULL, 0);
 422
 423   ret = memcmp (b1->data, b2->data, MIN (b1->size, b2->size));
 424   if (ret == 0 && b1->size != b2->size)
 425       ret = b1->size < b2->size ? -1 : 1;
 426   return ret;
 427 }
 428
 429 static gpointer
 430 try_steal_and_unref (GBytes         *bytes,
 431                      GDestroyNotify  free_func,
 432                      gsize          *size)
 433 {
 434   gpointer result;
 435
 436   if (bytes->free_func != free_func || bytes->data == NULL ||
 437       bytes->user_data != bytes->data)
 438     return NULL;
 439
 440   /* Are we the only reference? */
 441   if (g_atomic_int_get (&bytes->ref_count) == 1)
 442     {
 443       *size = bytes->size;
 444       result = (gpointer)bytes->data;
 445       g_slice_free (GBytes, bytes);
 446       return result;
 447     }
 448
 449   return NULL;
 450 }
 451
 452
 453 /**
 454  * g_bytes_unref_to_data:
 455  * @bytes: (transfer full): a #GBytes
 456  * @size: (out): location to place the length of the returned data
 457  *
 458  * Unreferences the bytes, and returns a pointer the same byte data
 459  * contents.
 460  *
 461  * As an optimization, the byte data is returned without copying if this was
 462  * the last reference to bytes and bytes was created with g_bytes_new(),
 463  * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
 464  * data is copied.
 465  *
 466  * Returns: (transfer full) (array length=size) (element-type guint8)
 467  *          (not nullable): a pointer to the same byte data, which should be
 468  *          freed with g_free()
 469  *
 470  * Since: 2.32
 471  */
 472 gpointer
 473 g_bytes_unref_to_data (GBytes *bytes,
 474                        gsize  *size)
 475 {
 476   gpointer result;
 477
 478   g_return_val_if_fail (bytes != NULL, NULL);
 479   g_return_val_if_fail (size != NULL, NULL);
 480
 481   /*
 482    * Optimal path: if this is was the last reference, then we can return
 483    * the data from this GBytes without copying.
 484    */
 485
 486   result = try_steal_and_unref (bytes, g_free, size);
 487   if (result == NULL)
 488     {
 489       /*
 490        * Copy: Non g_malloc (or compatible) allocator, or static memory,
 491        * so we have to copy, and then unref.
 492        */
 493       result = g_memdup (bytes->data, bytes->size);
 494       *size = bytes->size;
 495       g_bytes_unref (bytes);
 496     }
 497
 498   return result;
 499 }
 500
 501 /**
 502  * g_bytes_unref_to_array:
 503  * @bytes: (transfer full): a #GBytes
 504  *
 505  * Unreferences the bytes, and returns a new mutable #GByteArray containing
 506  * the same byte data.
 507  *
 508  * As an optimization, the byte data is transferred to the array without copying
 509  * if this was the last reference to bytes and bytes was created with
 510  * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
 511  * other cases the data is copied.
 512  *
 513  * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
 514  *
 515  * Since: 2.32
 516  */
 517 GByteArray *
 518 g_bytes_unref_to_array (GBytes *bytes)
 519 {
 520   gpointer data;
 521   gsize size;
 522
 523   g_return_val_if_fail (bytes != NULL, NULL);
 524
 525   data = g_bytes_unref_to_data (bytes, &size);
 526   return g_byte_array_new_take (data, size);
 527 }