Commit fcc69fd3 authored by Stef Walter's avatar Stef Walter

GBytes: A new type for an immutable set of bytes.

 * Represents an immutable reference counted block of memory.
 * This is basically the internal glib GBuffer structure exposed,
   renamed, and with some additional capabilities.
 * The GBytes name comes from python3's immutable 'bytes' type
 * GBytes can be safely used as keys in hash tables, and have
   functions for doing so: g_bytes_hash, g_bytes_equal
 * GByteArray is a mutable form of GBytes, and vice versa. There
   are functions for converting from one to the other efficiently:
   g_bytes_unref_to_array() and g_byte_array_free_to_bytes()
 * Adds g_byte_array_new_take() to support above functions

https://bugzilla.gnome.org/show_bug.cgi?id=663291
parent 069ec371
......@@ -46,7 +46,7 @@ IGNORE_HFILES = \
gnulib \
pcre \
update-pcre \
gbufferprivate.h \
gbytesprivate.h \
gvariant-internal.h \
gvariant-serialiser.h \
gvariant-core.h \
......
......@@ -2382,8 +2382,10 @@ g_ptr_array_foreach
<SECTION>
<TITLE>Byte Arrays</TITLE>
<FILE>arrays_byte</FILE>
<SUBSECTION>
GByteArray
g_byte_array_new
g_byte_array_new_take
g_byte_array_sized_new
g_byte_array_ref
g_byte_array_unref
......@@ -2396,7 +2398,24 @@ g_byte_array_sort
g_byte_array_sort_with_data
g_byte_array_set_size
g_byte_array_free
g_byte_array_free_to_bytes
<SUBSECTION>
GBytes
g_bytes_new
g_bytes_new_take
g_bytes_new_static
g_bytes_new_with_free_func
g_bytes_new_from_bytes
g_bytes_get_data
g_bytes_get_size
g_bytes_hash
g_bytes_equal
g_bytes_compare
g_bytes_ref
g_bytes_unref
g_bytes_unref_to_data
g_bytes_unref_to_array
</SECTION>
<SECTION>
......
......@@ -349,6 +349,7 @@ G_TYPE_MATCH_INFO
G_TYPE_ARRAY
G_TYPE_BYTE_ARRAY
G_TYPE_PTR_ARRAY
G_TYPE_BYTES
G_TYPE_VARIANT_TYPE
G_TYPE_ERROR
G_TYPE_DATE_TIME
......
......@@ -130,8 +130,8 @@ libglib_2_0_la_SOURCES = \
gbitlock.c \
gbookmarkfile.c \
gbsearcharray.h \
gbuffer.c \
gbufferprivate.h \
gbytes.c \
gbytes.h \
gcharset.c \
gchecksum.c \
gconvert.c \
......@@ -262,6 +262,7 @@ glibsubinclude_HEADERS = \
gbase64.h \
gbitlock.h \
gbookmarkfile.h \
gbytes.h \
gcharset.h \
gchecksum.h \
gconvert.h \
......
......@@ -35,8 +35,10 @@
#include "garray.h"
#include "gbytes.h"
#include "gslice.h"
#include "gmem.h"
#include "gtestutils.h"
#include "gthread.h"
#include "gmessages.h"
#include "gqsort.h"
......@@ -1344,16 +1346,13 @@ g_ptr_array_foreach (GPtrArray *array,
/**
* SECTION:arrays_byte
* @title: Byte Arrays
* @short_description: arrays of bytes, which grow automatically as
* elements are added
* @short_description: arrays of bytes
*
* #GByteArray is based on #GArray, to provide arrays of bytes which
* grow automatically as elements are added.
* #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
* of bytes which grow automatically as elements are added.
*
* To create a new #GByteArray use g_byte_array_new().
*
* To add elements to a #GByteArray, use g_byte_array_append(), and
* g_byte_array_prepend().
* To create a new #GByteArray use g_byte_array_new(). To add elements to a
* #GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
*
* To set the size of a #GByteArray, use g_byte_array_set_size().
*
......@@ -1380,6 +1379,9 @@ g_ptr_array_foreach (GPtrArray *array,
* g_byte_array_free (gbarray, TRUE);
* </programlisting>
* </example>
*
* See #GBytes if you are interested in an immutable object representing a
* sequence of bytes.
**/
/**
......@@ -1403,6 +1405,36 @@ GByteArray* g_byte_array_new (void)
return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0);
}
/**
* g_byte_array_new_take:
* @data: (array length=len): byte data for the array
* @len: length of @data
*
* Create byte array containing the data. The data will be owned by the array
* and will be freed with g_free(), i.e. it could be allocated using g_strdup().
*
* Since: 2.32
*
* Returns: (transfer full): a new #GByteArray
*/
GByteArray *
g_byte_array_new_take (guint8 *data,
gsize len)
{
GByteArray *array;
GRealArray *real;
array = g_byte_array_new ();
real = (GRealArray *)array;
g_assert (real->data == NULL);
g_assert (real->len == 0);
real->data = data;
real->len = len;
return array;
}
/**
* g_byte_array_sized_new:
* @reserved_size: number of bytes preallocated.
......@@ -1436,6 +1468,35 @@ guint8* g_byte_array_free (GByteArray *array,
return (guint8*) g_array_free ((GArray*) array, free_segment);
}
/**
* g_byte_array_free_to_bytes:
* @array: (transfer full): a #GByteArray
*
* Transfers the data from the #GByteArray into a new immutable #GBytes.
*
* The #GByteArray is freed unless the reference count of @array is greater
* than one, the #GByteArray wrapper is preserved but the size of @array
* will be set to zero.
*
* This is identical to using g_bytes_new_take() and g_byte_array_free()
* together.
*
* Since: 2.32
*
* Returns: (transfer full): a new immutable #GBytes representing same byte
* data that was in the array
*/
GBytes *
g_byte_array_free_to_bytes (GByteArray *array)
{
gsize length;
g_return_val_if_fail (array != NULL, NULL);
length = array->len;
return g_bytes_new_take (g_byte_array_free (array, FALSE), length);
}
/**
* g_byte_array_ref:
* @array: A #GByteArray.
......
......@@ -35,6 +35,7 @@
G_BEGIN_DECLS
typedef struct _GBytes GBytes;
typedef struct _GArray GArray;
typedef struct _GByteArray GByteArray;
typedef struct _GPtrArray GPtrArray;
......@@ -150,9 +151,12 @@ void g_ptr_array_foreach (GPtrArray *array,
*/
GByteArray* g_byte_array_new (void);
GByteArray* g_byte_array_new_take (guint8 *data,
gsize len);
GByteArray* g_byte_array_sized_new (guint reserved_size);
guint8* g_byte_array_free (GByteArray *array,
gboolean free_segment);
GBytes* g_byte_array_free_to_bytes (GByteArray *array);
GByteArray *g_byte_array_ref (GByteArray *array);
void g_byte_array_unref (GByteArray *array);
GByteArray* g_byte_array_append (GByteArray *array,
......
/*
* Copyright © 2009, 2010 Codethink Limited
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the licence, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*
* Author: Ryan Lortie <desrt@desrt.ca>
*/
#include "config.h"
#include "gbufferprivate.h"
#include <glib/gstrfuncs.h>
#include <glib/gatomic.h>
#include <glib/gslice.h>
#include <glib/gmem.h>
typedef struct
{
GBuffer buffer;
GDestroyNotify user_destroy;
gpointer user_data;
} GUserNotifyBuffer;
static void
g_buffer_free_gfree (GBuffer *buffer)
{
g_free ((gpointer) buffer->data);
g_slice_free (GBuffer, buffer);
}
/* < private >
* g_buffer_new_from_data:
* @data: the data to be used for the buffer
* @size: the size of @data
*
* Creates a new #GBuffer from @data.
*
* @data is copied.
*
* Returns: a reference to a new #GBuffer
*/
GBuffer *
g_buffer_new_from_data (gconstpointer data,
gsize size)
{
GBuffer *buffer;
buffer = g_slice_new (GBuffer);
buffer->data = g_memdup (data, size);
buffer->size = size;
buffer->free_func = g_buffer_free_gfree;
buffer->ref_count = 1;
return buffer;
}
/* < private >
* g_buffer_new_take_data:
* @data: the data to be used for the buffer
* @size: the size of @data
* returns: a reference to a new #GBuffer
*
* Creates a new #GBuffer from @data.
*
* @data must have been created by a call to g_malloc(), g_malloc0() or
* g_realloc() or by one of the many functions that wrap these calls
* (such as g_new(), g_strdup(), etc).
*
* After this call, @data belongs to the buffer and may no longer be
* modified by the caller. g_free() will be called on @data when the
* buffer is no longer in use.
*/
GBuffer *
g_buffer_new_take_data (gpointer data,
gsize size)
{
GBuffer *buffer;
buffer = g_slice_new (GBuffer);
buffer->data = data;
buffer->size = size;
buffer->free_func = g_buffer_free_gfree;
buffer->ref_count = 1;
return buffer;
}
static void
g_buffer_free (GBuffer *buffer)
{
g_slice_free (GBuffer, buffer);
}
/* < private >
* g_buffer_new_from_static_data:
* @data: the data to be used for the buffer
* @size: the size of @data
*
* Creates a new #GBuffer from static data.
*
* @data must be static (ie: never modified or freed).
*
* Returns: a reference to a new #GBuffer
*/
GBuffer *
g_buffer_new_from_static_data (gconstpointer data,
gsize size)
{
GBuffer *buffer;
buffer = g_slice_new (GBuffer);
buffer->data = data;
buffer->size = size;
buffer->free_func = g_buffer_free;
buffer->ref_count = 1;
return buffer;
}
static void
g_buffer_free_usernotify (GBuffer *buffer)
{
GUserNotifyBuffer *ubuffer = (GUserNotifyBuffer *) buffer;
ubuffer->user_destroy (ubuffer->user_data);
g_slice_free (GUserNotifyBuffer, ubuffer);
}
/* < private >
* g_buffer_new_from_pointer:
* @data: the data to be used for the buffer
* @size: the size of @data
* @notify: the function to call to release the data
* @user_data: the data to pass to @notify
*
* Creates a #GBuffer from @data.
*
* When the last reference is dropped, @notify will be called on
* @user_data.
*
* @data must not be modified after this call is made, until @notify has
* been called to indicate that the buffer is no longer in use.
*
* Returns: a reference to a new #GBuffer
*/
GBuffer *
g_buffer_new_from_pointer (gconstpointer data,
gsize size,
GDestroyNotify notify,
gpointer user_data)
{
GUserNotifyBuffer *ubuffer;
ubuffer = g_slice_new (GUserNotifyBuffer);
ubuffer->buffer.data = data;
ubuffer->buffer.size = size;
ubuffer->buffer.free_func = g_buffer_free_usernotify;
ubuffer->buffer.ref_count = 1;
ubuffer->user_destroy = notify;
ubuffer->user_data = user_data;
return (GBuffer *) ubuffer;
}
/* < private >
* g_buffer_ref:
* @buffer: a #GBuffer
*
* Increase the reference count on @buffer.
*
* Returns: @buffer
*/
GBuffer *
g_buffer_ref (GBuffer *buffer)
{
g_atomic_int_inc (&buffer->ref_count);
return buffer;
}
/* < private >
* g_buffer_unref:
* @buffer: a #GBuffer
*
* Releases a reference on @buffer. This may result in the buffer being
* freed.
*/
void
g_buffer_unref (GBuffer *buffer)
{
if (g_atomic_int_dec_and_test (&buffer->ref_count))
if (buffer->free_func != NULL)
buffer->free_func (buffer);
}
/*
* Copyright © 2009, 2010 Codethink Limited
* Copyright © 2011 Collabora Ltd.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the licence, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*
* Author: Ryan Lortie <desrt@desrt.ca>
* Stef Walter <stefw@collabora.co.uk>
*/
#include "config.h"
#include "gbytes.h"
#include <glib/garray.h>
#include <glib/gstrfuncs.h>
#include <glib/gatomic.h>
#include <glib/gslice.h>
#include <glib/gtestutils.h>
#include <glib/gmem.h>
#include <glib/gmessages.h>
#include <string.h>
/**
* GBytes:
*
* A simple refcounted data type representing an immutable byte sequence
* from an unspecified origin.
*
* The purpose of a #GBytes is to keep the memory region that it holds
* alive for as long as anyone holds a reference to the bytes. When
* the last reference count is dropped, the memory is released. Multiple
* unrelated callers can use byte data in the #GBytes without coordinating
* their activities, resting assured that the byte data will not change or
* move while they hold a reference.
*
* A #GBytes can come from many different origins that may have
* different procedures for freeing the memory region. Examples are
* memory from g_malloc(), from memory slices, from a #GMappedFile or
* memory from other allocators.
*
* #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
* g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
* #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
* function to g_tree_new().
*
* The data pointed to by this bytes must not be modified. For a mutable
* array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
* mutable array for a #GBytes sequence. To create an immutable #GBytes from
* a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
*
* Since: 2.32
**/
struct _GBytes
{
gconstpointer data;
gsize size;
gint ref_count;
GDestroyNotify free_func;
gpointer user_data;
};
/**
* g_bytes_new:
* @data: (array length=size): the data to be used for the bytes
* @size: the size of @data
*
* Creates a new #GBytes from @data.
*
* @data is copied.
*
* Returns: (transfer full): a new #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_new (gconstpointer data,
gsize size)
{
return g_bytes_new_take (g_memdup (data, size), size);
}
/**
* g_bytes_new_take:
* @data: (transfer full) (array length=size): the data to be used for the bytes
* @size: the size of @data
*
* Creates a new #GBytes from @data.
*
* After this call, @data belongs to the bytes and may no longer be
* modified by the caller. g_free() will be called on @data when the
* bytes is no longer in use. Because of this @data must have been created by
* a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
* functions that wrap these calls (such as g_new(), g_strdup(), etc).
*
* For creating #GBytes with memory from other allocators, see
* g_bytes_new_with_free_func().
*
* Returns: (transfer full): a new #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_new_take (gpointer data,
gsize size)
{
return g_bytes_new_with_free_func (data, size, g_free, data);
}
/**
* g_bytes_new_static:
* @data: (array length=size): the data to be used for the bytes
* @size: the size of @data
*
* Creates a new #GBytes from static data.
*
* @data must be static (ie: never modified or freed).
*
* Returns: (transfer full): a new #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_new_static (gconstpointer data,
gsize size)
{
return g_bytes_new_with_free_func (data, size, NULL, NULL);
}
/**
* g_bytes_new_with_free_func:
* @data: (array length=size): the data to be used for the bytes
* @size: the size of @data
* @free_func: the function to call to release the data
* @user_data: data to pass to @free_func
*
* Creates a #GBytes from @data.
*
* When the last reference is dropped, @free_func will be called with the
* @user_data argument.
*
* @data must not be modified after this call is made until @free_func has
* been called to indicate that the bytes is no longer in use.
*
* Returns: (transfer full): a new #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_new_with_free_func (gconstpointer data,
gsize size,
GDestroyNotify free_func,
gpointer user_data)
{
GBytes *bytes;
bytes = g_slice_new (GBytes);
bytes->data = data;
bytes->size = size;
bytes->free_func = free_func;
bytes->user_data = user_data;
bytes->ref_count = 1;
return (GBytes *)bytes;
}
/**
* g_bytes_new_from_bytes:
* @bytes: a #GBytes
* @offset: offset which subsection starts at
* @length: length of subsection
*
* Creates a #GBytes which is a subsection of another #GBytes. The @offset +
* @length may not be longer than the size of @bytes.
*
* A reference to @bytes will be held by the newly created #GBytes until
* the byte data is no longer needed.
*
* Returns: (transfer full): a new #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_new_from_bytes (GBytes *bytes,
gsize offset,
gsize length)
{
g_return_val_if_fail (bytes != NULL, NULL);
g_return_val_if_fail (offset <= bytes->size, NULL);
g_return_val_if_fail (offset + length <= bytes->size, NULL);
return g_bytes_new_with_free_func ((gchar *)bytes->data + offset, length,
(GDestroyNotify)g_bytes_unref, g_bytes_ref (bytes));
}
/**
* g_bytes_get_data:
* @bytes: a #GBytes
*
* Get the byte data in the #GBytes. This data should not be modified.
*
* This function will always return the same pointer for a given #GBytes.
*
* Returns: a pointer to the byte data
*
* Since: 2.32
*/
gconstpointer
g_bytes_get_data (GBytes *bytes)
{
g_return_val_if_fail (bytes != NULL, NULL);
return bytes->data;
}
/**
* g_bytes_get_size:
* @bytes: a #GBytes
*
* Get the size of the byte data in the #GBytes.
*
* This function will always return the same value for a given #GBytes.
*
* Returns: the size
*
* Since: 2.32
*/
gsize
g_bytes_get_size (GBytes *bytes)
{
g_return_val_if_fail (bytes != NULL, 0);
return bytes->size;
}
/**
* g_bytes_ref:
* @bytes: a #GBytes
*
* Increase the reference count on @bytes.
*
* Returns: the #GBytes
*
* Since: 2.32
*/
GBytes *
g_bytes_ref (GBytes *bytes)
{
g_return_val_if_fail (bytes != NULL, NULL);
g_atomic_int_inc (&bytes->ref_count);
return bytes;
}
/**
* g_bytes_unref:
* @bytes: (allow-none): a #GBytes
*
* Releases a reference on @bytes. This may result in the bytes being
* freed.
*
* Since: 2.32
*/
void
g_bytes_unref (GBytes *bytes)
{
if (bytes == NULL)
return;
if (g_atomic_int_dec_and_test (&bytes->ref_count))
{
if (bytes->free_func != NULL)
bytes->free_func (bytes->user_data);
g_slice_free (GBytes, bytes);
}
}
/**
* g_bytes_equal:
* @bytes1: (type GLib.Bytes): a pointer to a #GBytes
* @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
*
* Compares the two #GBytes values being pointed to and returns
* %TRUE if they are equal.
*
* This function can be passed to g_hash_table_new() as the @key_equal_func
* parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
*
* Returns: %TRUE if the two keys match.
*
* Since: 2.32
*/
gboolean
g_bytes_equal (gconstpointer bytes1,
gconstpointer bytes2)
{
const GBytes *b1 = bytes1;
const GBytes *b2 = bytes2;
g_return_val_if_fail (bytes1 != NULL, FALSE);
g_return_val_if_fail (bytes2 != NULL, FALSE);
return b1->size == b2->size &&
memcmp (b1->data, b2->data, b1->size) == 0;
}
/**
* g_bytes_hash:
* @bytes: (type GLib.Bytes): a pointer to a #GBytes key
*
* Creates an integer hash code for the byte data in the #GBytes.
*
* This function can be passed to g_hash_table_new() as the @key_equal_func
* parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
*
* Returns: a hash value corresponding to the key.
*
* Since: 2.32
*/
guint
g_bytes_hash (gconstpointer bytes)
{
const GBytes *a = bytes;
const signed char *p, *e;
guint32 h = 5381;
g_return_val_if_fail (bytes != NULL, 0);
for (p = (signed char *)a->data, e = (signed char *)a->data + a->size; p != e; p++)
h = (h << 5) + h + *p;