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