nexmon – Blame information for rev 1

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