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