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