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 (data: g_memdup2 (mem: data, byte_size: 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, free_func: g_free, user_data: 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 (arc: &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 (data: base, size: length, |
248 | free_func: (GDestroyNotify)g_bytes_unref, user_data: 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 (arc: &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 (arc: &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 | (b1->size == 0 || memcmp (s1: b1->data, s2: b2->data, n: 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 lexicographical order. |
407 | * |
408 | * If @bytes1 and @bytes2 have different length but the shorter one is a |
409 | * prefix of the longer one then the shorter one is considered to be less than |
410 | * the longer one. Otherwise the first byte where both differ is used for |
411 | * comparison. If @bytes1 has a smaller value at that position it is |
412 | * considered less, otherwise greater than @bytes2. |
413 | * |
414 | * Returns: a negative value if @bytes1 is less than @bytes2, a positive value |
415 | * if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to |
416 | * @bytes2 |
417 | * |
418 | * |
419 | * Since: 2.32 |
420 | */ |
421 | gint |
422 | g_bytes_compare (gconstpointer bytes1, |
423 | gconstpointer bytes2) |
424 | { |
425 | const GBytes *b1 = bytes1; |
426 | const GBytes *b2 = bytes2; |
427 | gint ret; |
428 | |
429 | g_return_val_if_fail (bytes1 != NULL, 0); |
430 | g_return_val_if_fail (bytes2 != NULL, 0); |
431 | |
432 | ret = memcmp (s1: b1->data, s2: b2->data, MIN (b1->size, b2->size)); |
433 | if (ret == 0 && b1->size != b2->size) |
434 | ret = b1->size < b2->size ? -1 : 1; |
435 | return ret; |
436 | } |
437 | |
438 | static gpointer |
439 | try_steal_and_unref (GBytes *bytes, |
440 | GDestroyNotify free_func, |
441 | gsize *size) |
442 | { |
443 | gpointer result; |
444 | |
445 | if (bytes->free_func != free_func || bytes->data == NULL || |
446 | bytes->user_data != bytes->data) |
447 | return NULL; |
448 | |
449 | /* Are we the only reference? */ |
450 | if (g_atomic_ref_count_compare (arc: &bytes->ref_count, val: 1)) |
451 | { |
452 | *size = bytes->size; |
453 | result = (gpointer)bytes->data; |
454 | g_slice_free (GBytes, bytes); |
455 | return result; |
456 | } |
457 | |
458 | return NULL; |
459 | } |
460 | |
461 | |
462 | /** |
463 | * g_bytes_unref_to_data: |
464 | * @bytes: (transfer full): a #GBytes |
465 | * @size: (out): location to place the length of the returned data |
466 | * |
467 | * Unreferences the bytes, and returns a pointer the same byte data |
468 | * contents. |
469 | * |
470 | * As an optimization, the byte data is returned without copying if this was |
471 | * the last reference to bytes and bytes was created with g_bytes_new(), |
472 | * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the |
473 | * data is copied. |
474 | * |
475 | * Returns: (transfer full) (array length=size) (element-type guint8) |
476 | * (not nullable): a pointer to the same byte data, which should be |
477 | * freed with g_free() |
478 | * |
479 | * Since: 2.32 |
480 | */ |
481 | gpointer |
482 | g_bytes_unref_to_data (GBytes *bytes, |
483 | gsize *size) |
484 | { |
485 | gpointer result; |
486 | |
487 | g_return_val_if_fail (bytes != NULL, NULL); |
488 | g_return_val_if_fail (size != NULL, NULL); |
489 | |
490 | /* |
491 | * Optimal path: if this is was the last reference, then we can return |
492 | * the data from this GBytes without copying. |
493 | */ |
494 | |
495 | result = try_steal_and_unref (bytes, free_func: g_free, size); |
496 | if (result == NULL) |
497 | { |
498 | /* |
499 | * Copy: Non g_malloc (or compatible) allocator, or static memory, |
500 | * so we have to copy, and then unref. |
501 | */ |
502 | result = g_memdup2 (mem: bytes->data, byte_size: bytes->size); |
503 | *size = bytes->size; |
504 | g_bytes_unref (bytes); |
505 | } |
506 | |
507 | return result; |
508 | } |
509 | |
510 | /** |
511 | * g_bytes_unref_to_array: |
512 | * @bytes: (transfer full): a #GBytes |
513 | * |
514 | * Unreferences the bytes, and returns a new mutable #GByteArray containing |
515 | * the same byte data. |
516 | * |
517 | * As an optimization, the byte data is transferred to the array without copying |
518 | * if this was the last reference to bytes and bytes was created with |
519 | * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all |
520 | * other cases the data is copied. |
521 | * |
522 | * Do not use it if @bytes contains more than %G_MAXUINT |
523 | * bytes. #GByteArray stores the length of its data in #guint, which |
524 | * may be shorter than #gsize, that @bytes is using. |
525 | * |
526 | * Returns: (transfer full): a new mutable #GByteArray containing the same byte data |
527 | * |
528 | * Since: 2.32 |
529 | */ |
530 | GByteArray * |
531 | g_bytes_unref_to_array (GBytes *bytes) |
532 | { |
533 | gpointer data; |
534 | gsize size; |
535 | |
536 | g_return_val_if_fail (bytes != NULL, NULL); |
537 | |
538 | data = g_bytes_unref_to_data (bytes, size: &size); |
539 | return g_byte_array_new_take (data, len: size); |
540 | } |
541 | |