1/* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * gdataset.c: Generic dataset mechanism, similar to GtkObject data.
5 * Copyright (C) 1998 Tim Janik
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21/*
22 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
23 * file for a list of people on the GLib Team. See the ChangeLog
24 * files for a list of changes. These files are distributed with
25 * GLib at ftp://ftp.gtk.org/pub/gtk/.
26 */
27
28/*
29 * MT safe ; except for g_data*_foreach()
30 */
31
32#include "config.h"
33
34#include <string.h>
35
36#include "gdataset.h"
37#include "gbitlock.h"
38
39#include "gslice.h"
40#include "gdatasetprivate.h"
41#include "ghash.h"
42#include "gquark.h"
43#include "gstrfuncs.h"
44#include "gtestutils.h"
45#include "gthread.h"
46#include "glib_trace.h"
47
48/**
49 * SECTION:datasets
50 * @title: Datasets
51 * @short_description: associate groups of data elements with
52 * particular memory locations
53 *
54 * Datasets associate groups of data elements with particular memory
55 * locations. These are useful if you need to associate data with a
56 * structure returned from an external library. Since you cannot modify
57 * the structure, you use its location in memory as the key into a
58 * dataset, where you can associate any number of data elements with it.
59 *
60 * There are two forms of most of the dataset functions. The first form
61 * uses strings to identify the data elements associated with a
62 * location. The second form uses #GQuark identifiers, which are
63 * created with a call to g_quark_from_string() or
64 * g_quark_from_static_string(). The second form is quicker, since it
65 * does not require looking up the string in the hash table of #GQuark
66 * identifiers.
67 *
68 * There is no function to create a dataset. It is automatically
69 * created as soon as you add elements to it.
70 *
71 * To add data elements to a dataset use g_dataset_id_set_data(),
72 * g_dataset_id_set_data_full(), g_dataset_set_data() and
73 * g_dataset_set_data_full().
74 *
75 * To get data elements from a dataset use g_dataset_id_get_data() and
76 * g_dataset_get_data().
77 *
78 * To iterate over all data elements in a dataset use
79 * g_dataset_foreach() (not thread-safe).
80 *
81 * To remove data elements from a dataset use
82 * g_dataset_id_remove_data() and g_dataset_remove_data().
83 *
84 * To destroy a dataset, use g_dataset_destroy().
85 **/
86
87/**
88 * SECTION:datalist
89 * @title: Keyed Data Lists
90 * @short_description: lists of data elements which are accessible by a
91 * string or GQuark identifier
92 *
93 * Keyed data lists provide lists of arbitrary data elements which can
94 * be accessed either with a string or with a #GQuark corresponding to
95 * the string.
96 *
97 * The #GQuark methods are quicker, since the strings have to be
98 * converted to #GQuarks anyway.
99 *
100 * Data lists are used for associating arbitrary data with #GObjects,
101 * using g_object_set_data() and related functions.
102 *
103 * To create a datalist, use g_datalist_init().
104 *
105 * To add data elements to a datalist use g_datalist_id_set_data(),
106 * g_datalist_id_set_data_full(), g_datalist_set_data() and
107 * g_datalist_set_data_full().
108 *
109 * To get data elements from a datalist use g_datalist_id_get_data()
110 * and g_datalist_get_data().
111 *
112 * To iterate over all data elements in a datalist use
113 * g_datalist_foreach() (not thread-safe).
114 *
115 * To remove data elements from a datalist use
116 * g_datalist_id_remove_data() and g_datalist_remove_data().
117 *
118 * To remove all data elements from a datalist, use g_datalist_clear().
119 **/
120
121/**
122 * GData:
123 *
124 * The #GData struct is an opaque data structure to represent a
125 * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be
126 * accessed via the following functions.
127 **/
128
129/**
130 * GDestroyNotify:
131 * @data: the data element.
132 *
133 * Specifies the type of function which is called when a data element
134 * is destroyed. It is passed the pointer to the data element and
135 * should free any memory and resources allocated for it.
136 **/
137
138#define G_DATALIST_FLAGS_MASK_INTERNAL 0x7
139
140/* datalist pointer accesses have to be carried out atomically */
141#define G_DATALIST_GET_POINTER(datalist) \
142 ((GData*) ((gsize) g_atomic_pointer_get (datalist) & ~(gsize) G_DATALIST_FLAGS_MASK_INTERNAL))
143
144#define G_DATALIST_SET_POINTER(datalist, pointer) G_STMT_START { \
145 gpointer _oldv, _newv; \
146 do { \
147 _oldv = g_atomic_pointer_get (datalist); \
148 _newv = (gpointer) (((gsize) _oldv & G_DATALIST_FLAGS_MASK_INTERNAL) | (gsize) pointer); \
149 } while (!g_atomic_pointer_compare_and_exchange ((void**) datalist, _oldv, _newv)); \
150} G_STMT_END
151
152/* --- structures --- */
153typedef struct {
154 GQuark key;
155 gpointer data;
156 GDestroyNotify destroy;
157} GDataElt;
158
159typedef struct _GDataset GDataset;
160struct _GData
161{
162 guint32 len; /* Number of elements */
163 guint32 alloc; /* Number of allocated elements */
164 GDataElt data[1]; /* Flexible array */
165};
166
167struct _GDataset
168{
169 gconstpointer location;
170 GData *datalist;
171};
172
173
174/* --- prototypes --- */
175static inline GDataset* g_dataset_lookup (gconstpointer dataset_location);
176static inline void g_datalist_clear_i (GData **datalist);
177static void g_dataset_destroy_internal (GDataset *dataset);
178static inline gpointer g_data_set_internal (GData **datalist,
179 GQuark key_id,
180 gpointer data,
181 GDestroyNotify destroy_func,
182 GDataset *dataset);
183static void g_data_initialize (void);
184
185/* Locking model:
186 * Each standalone GDataList is protected by a bitlock in the datalist pointer,
187 * which protects that modification of the non-flags part of the datalist pointer
188 * and the contents of the datalist.
189 *
190 * For GDataSet we have a global lock g_dataset_global that protects
191 * the global dataset hash and cache, and additionally it protects the
192 * datalist such that we can avoid to use the bit lock in a few places
193 * where it is easy.
194 */
195
196/* --- variables --- */
197G_LOCK_DEFINE_STATIC (g_dataset_global);
198static GHashTable *g_dataset_location_ht = NULL;
199static GDataset *g_dataset_cached = NULL; /* should this be
200 thread specific? */
201
202/* --- functions --- */
203
204#define DATALIST_LOCK_BIT 2
205
206static void
207g_datalist_lock (GData **datalist)
208{
209 g_pointer_bit_lock ((void **)datalist, DATALIST_LOCK_BIT);
210}
211
212static void
213g_datalist_unlock (GData **datalist)
214{
215 g_pointer_bit_unlock ((void **)datalist, DATALIST_LOCK_BIT);
216}
217
218/* Called with the datalist lock held, or the dataset global
219 * lock for dataset lists
220 */
221static void
222g_datalist_clear_i (GData **datalist)
223{
224 GData *data;
225 guint i;
226
227 data = G_DATALIST_GET_POINTER (datalist);
228 G_DATALIST_SET_POINTER (datalist, NULL);
229
230 if (data)
231 {
232 G_UNLOCK (g_dataset_global);
233 for (i = 0; i < data->len; i++)
234 {
235 if (data->data[i].data && data->data[i].destroy)
236 data->data[i].destroy (data->data[i].data);
237 }
238 G_LOCK (g_dataset_global);
239
240 g_free (mem: data);
241 }
242
243}
244
245/**
246 * g_datalist_clear: (skip)
247 * @datalist: a datalist.
248 *
249 * Frees all the data elements of the datalist.
250 * The data elements' destroy functions are called
251 * if they have been set.
252 **/
253void
254g_datalist_clear (GData **datalist)
255{
256 GData *data;
257 guint i;
258
259 g_return_if_fail (datalist != NULL);
260
261 g_datalist_lock (datalist);
262
263 data = G_DATALIST_GET_POINTER (datalist);
264 G_DATALIST_SET_POINTER (datalist, NULL);
265
266 g_datalist_unlock (datalist);
267
268 if (data)
269 {
270 for (i = 0; i < data->len; i++)
271 {
272 if (data->data[i].data && data->data[i].destroy)
273 data->data[i].destroy (data->data[i].data);
274 }
275
276 g_free (mem: data);
277 }
278}
279
280/* HOLDS: g_dataset_global_lock */
281static inline GDataset*
282g_dataset_lookup (gconstpointer dataset_location)
283{
284 GDataset *dataset;
285
286 if (g_dataset_cached && g_dataset_cached->location == dataset_location)
287 return g_dataset_cached;
288
289 dataset = g_hash_table_lookup (hash_table: g_dataset_location_ht, key: dataset_location);
290 if (dataset)
291 g_dataset_cached = dataset;
292
293 return dataset;
294}
295
296/* HOLDS: g_dataset_global_lock */
297static void
298g_dataset_destroy_internal (GDataset *dataset)
299{
300 gconstpointer dataset_location;
301
302 dataset_location = dataset->location;
303 while (dataset)
304 {
305 if (G_DATALIST_GET_POINTER(&dataset->datalist) == NULL)
306 {
307 if (dataset == g_dataset_cached)
308 g_dataset_cached = NULL;
309 g_hash_table_remove (hash_table: g_dataset_location_ht, key: dataset_location);
310 g_slice_free (GDataset, dataset);
311 break;
312 }
313
314 g_datalist_clear_i (datalist: &dataset->datalist);
315 dataset = g_dataset_lookup (dataset_location);
316 }
317}
318
319/**
320 * g_dataset_destroy:
321 * @dataset_location: (not nullable): the location identifying the dataset.
322 *
323 * Destroys the dataset, freeing all memory allocated, and calling any
324 * destroy functions set for data elements.
325 */
326void
327g_dataset_destroy (gconstpointer dataset_location)
328{
329 g_return_if_fail (dataset_location != NULL);
330
331 G_LOCK (g_dataset_global);
332 if (g_dataset_location_ht)
333 {
334 GDataset *dataset;
335
336 dataset = g_dataset_lookup (dataset_location);
337 if (dataset)
338 g_dataset_destroy_internal (dataset);
339 }
340 G_UNLOCK (g_dataset_global);
341}
342
343/* HOLDS: g_dataset_global_lock if dataset != null */
344static inline gpointer
345g_data_set_internal (GData **datalist,
346 GQuark key_id,
347 gpointer new_data,
348 GDestroyNotify new_destroy_func,
349 GDataset *dataset)
350{
351 GData *d, *old_d;
352 GDataElt old, *data, *data_last, *data_end;
353
354 g_datalist_lock (datalist);
355
356 d = G_DATALIST_GET_POINTER (datalist);
357
358 if (new_data == NULL) /* remove */
359 {
360 if (d)
361 {
362 data = d->data;
363 data_last = data + d->len - 1;
364 while (data <= data_last)
365 {
366 if (data->key == key_id)
367 {
368 old = *data;
369 if (data != data_last)
370 *data = *data_last;
371 d->len--;
372
373 /* We don't bother to shrink, but if all data are now gone
374 * we at least free the memory
375 */
376 if (d->len == 0)
377 {
378 G_DATALIST_SET_POINTER (datalist, NULL);
379 g_free (mem: d);
380 /* datalist may be situated in dataset, so must not be
381 * unlocked after we free it
382 */
383 g_datalist_unlock (datalist);
384
385 /* the dataset destruction *must* be done
386 * prior to invocation of the data destroy function
387 */
388 if (dataset)
389 g_dataset_destroy_internal (dataset);
390 }
391 else
392 {
393 g_datalist_unlock (datalist);
394 }
395
396 /* We found and removed an old value
397 * the GData struct *must* already be unlinked
398 * when invoking the destroy function.
399 * we use (new_data==NULL && new_destroy_func!=NULL) as
400 * a special hint combination to "steal"
401 * data without destroy notification
402 */
403 if (old.destroy && !new_destroy_func)
404 {
405 if (dataset)
406 G_UNLOCK (g_dataset_global);
407 old.destroy (old.data);
408 if (dataset)
409 G_LOCK (g_dataset_global);
410 old.data = NULL;
411 }
412
413 return old.data;
414 }
415 data++;
416 }
417 }
418 }
419 else
420 {
421 old.data = NULL;
422 if (d)
423 {
424 data = d->data;
425 data_end = data + d->len;
426 while (data < data_end)
427 {
428 if (data->key == key_id)
429 {
430 if (!data->destroy)
431 {
432 data->data = new_data;
433 data->destroy = new_destroy_func;
434 g_datalist_unlock (datalist);
435 }
436 else
437 {
438 old = *data;
439 data->data = new_data;
440 data->destroy = new_destroy_func;
441
442 g_datalist_unlock (datalist);
443
444 /* We found and replaced an old value
445 * the GData struct *must* already be unlinked
446 * when invoking the destroy function.
447 */
448 if (dataset)
449 G_UNLOCK (g_dataset_global);
450 old.destroy (old.data);
451 if (dataset)
452 G_LOCK (g_dataset_global);
453 }
454 return NULL;
455 }
456 data++;
457 }
458 }
459
460 /* The key was not found, insert it */
461 old_d = d;
462 if (d == NULL)
463 {
464 d = g_malloc (n_bytes: sizeof (GData));
465 d->len = 0;
466 d->alloc = 1;
467 }
468 else if (d->len == d->alloc)
469 {
470 d->alloc = d->alloc * 2;
471 d = g_realloc (mem: d, n_bytes: sizeof (GData) + (d->alloc - 1) * sizeof (GDataElt));
472 }
473 if (old_d != d)
474 G_DATALIST_SET_POINTER (datalist, d);
475
476 d->data[d->len].key = key_id;
477 d->data[d->len].data = new_data;
478 d->data[d->len].destroy = new_destroy_func;
479 d->len++;
480 }
481
482 g_datalist_unlock (datalist);
483
484 return NULL;
485
486}
487
488/**
489 * g_dataset_id_set_data_full: (skip)
490 * @dataset_location: (not nullable): the location identifying the dataset.
491 * @key_id: the #GQuark id to identify the data element.
492 * @data: the data element.
493 * @destroy_func: the function to call when the data element is
494 * removed. This function will be called with the data
495 * element and can be used to free any memory allocated
496 * for it.
497 *
498 * Sets the data element associated with the given #GQuark id, and also
499 * the function to call when the data element is destroyed. Any
500 * previous data with the same key is removed, and its destroy function
501 * is called.
502 **/
503/**
504 * g_dataset_set_data_full: (skip)
505 * @l: the location identifying the dataset.
506 * @k: the string to identify the data element.
507 * @d: the data element.
508 * @f: the function to call when the data element is removed. This
509 * function will be called with the data element and can be used to
510 * free any memory allocated for it.
511 *
512 * Sets the data corresponding to the given string identifier, and the
513 * function to call when the data element is destroyed.
514 **/
515/**
516 * g_dataset_id_set_data:
517 * @l: the location identifying the dataset.
518 * @k: the #GQuark id to identify the data element.
519 * @d: the data element.
520 *
521 * Sets the data element associated with the given #GQuark id. Any
522 * previous data with the same key is removed, and its destroy function
523 * is called.
524 **/
525/**
526 * g_dataset_set_data:
527 * @l: the location identifying the dataset.
528 * @k: the string to identify the data element.
529 * @d: the data element.
530 *
531 * Sets the data corresponding to the given string identifier.
532 **/
533/**
534 * g_dataset_id_remove_data:
535 * @l: the location identifying the dataset.
536 * @k: the #GQuark id identifying the data element.
537 *
538 * Removes a data element from a dataset. The data element's destroy
539 * function is called if it has been set.
540 **/
541/**
542 * g_dataset_remove_data:
543 * @l: the location identifying the dataset.
544 * @k: the string identifying the data element.
545 *
546 * Removes a data element corresponding to a string. Its destroy
547 * function is called if it has been set.
548 **/
549void
550g_dataset_id_set_data_full (gconstpointer dataset_location,
551 GQuark key_id,
552 gpointer data,
553 GDestroyNotify destroy_func)
554{
555 GDataset *dataset;
556
557 g_return_if_fail (dataset_location != NULL);
558 if (!data)
559 g_return_if_fail (destroy_func == NULL);
560 if (!key_id)
561 {
562 if (data)
563 g_return_if_fail (key_id > 0);
564 else
565 return;
566 }
567
568 G_LOCK (g_dataset_global);
569 if (!g_dataset_location_ht)
570 g_data_initialize ();
571
572 dataset = g_dataset_lookup (dataset_location);
573 if (!dataset)
574 {
575 dataset = g_slice_new (GDataset);
576 dataset->location = dataset_location;
577 g_datalist_init (datalist: &dataset->datalist);
578 g_hash_table_insert (hash_table: g_dataset_location_ht,
579 key: (gpointer) dataset->location,
580 value: dataset);
581 }
582
583 g_data_set_internal (datalist: &dataset->datalist, key_id, new_data: data, new_destroy_func: destroy_func, dataset);
584 G_UNLOCK (g_dataset_global);
585}
586
587/**
588 * g_datalist_id_set_data_full: (skip)
589 * @datalist: a datalist.
590 * @key_id: the #GQuark to identify the data element.
591 * @data: (nullable): the data element or %NULL to remove any previous element
592 * corresponding to @key_id.
593 * @destroy_func: (nullable): the function to call when the data element is
594 * removed. This function will be called with the data
595 * element and can be used to free any memory allocated
596 * for it. If @data is %NULL, then @destroy_func must
597 * also be %NULL.
598 *
599 * Sets the data corresponding to the given #GQuark id, and the
600 * function to be called when the element is removed from the datalist.
601 * Any previous data with the same key is removed, and its destroy
602 * function is called.
603 **/
604/**
605 * g_datalist_set_data_full: (skip)
606 * @dl: a datalist.
607 * @k: the string to identify the data element.
608 * @d: (nullable): the data element, or %NULL to remove any previous element
609 * corresponding to @k.
610 * @f: (nullable): the function to call when the data element is removed.
611 * This function will be called with the data element and can be used to
612 * free any memory allocated for it. If @d is %NULL, then @f must
613 * also be %NULL.
614 *
615 * Sets the data element corresponding to the given string identifier,
616 * and the function to be called when the data element is removed.
617 **/
618/**
619 * g_datalist_id_set_data:
620 * @dl: a datalist.
621 * @q: the #GQuark to identify the data element.
622 * @d: (nullable): the data element, or %NULL to remove any previous element
623 * corresponding to @q.
624 *
625 * Sets the data corresponding to the given #GQuark id. Any previous
626 * data with the same key is removed, and its destroy function is
627 * called.
628 **/
629/**
630 * g_datalist_set_data:
631 * @dl: a datalist.
632 * @k: the string to identify the data element.
633 * @d: (nullable): the data element, or %NULL to remove any previous element
634 * corresponding to @k.
635 *
636 * Sets the data element corresponding to the given string identifier.
637 **/
638/**
639 * g_datalist_id_remove_data:
640 * @dl: a datalist.
641 * @q: the #GQuark identifying the data element.
642 *
643 * Removes an element, using its #GQuark identifier.
644 **/
645/**
646 * g_datalist_remove_data:
647 * @dl: a datalist.
648 * @k: the string identifying the data element.
649 *
650 * Removes an element using its string identifier. The data element's
651 * destroy function is called if it has been set.
652 **/
653void
654g_datalist_id_set_data_full (GData **datalist,
655 GQuark key_id,
656 gpointer data,
657 GDestroyNotify destroy_func)
658{
659 g_return_if_fail (datalist != NULL);
660 if (!data)
661 g_return_if_fail (destroy_func == NULL);
662 if (!key_id)
663 {
664 if (data)
665 g_return_if_fail (key_id > 0);
666 else
667 return;
668 }
669
670 g_data_set_internal (datalist, key_id, new_data: data, new_destroy_func: destroy_func, NULL);
671}
672
673/**
674 * g_dataset_id_remove_no_notify: (skip)
675 * @dataset_location: (not nullable): the location identifying the dataset.
676 * @key_id: the #GQuark ID identifying the data element.
677 *
678 * Removes an element, without calling its destroy notification
679 * function.
680 *
681 * Returns: (nullable): the data previously stored at @key_id,
682 * or %NULL if none.
683 **/
684/**
685 * g_dataset_remove_no_notify: (skip)
686 * @l: the location identifying the dataset.
687 * @k: the string identifying the data element.
688 *
689 * Removes an element, without calling its destroy notifier.
690 **/
691gpointer
692g_dataset_id_remove_no_notify (gconstpointer dataset_location,
693 GQuark key_id)
694{
695 gpointer ret_data = NULL;
696
697 g_return_val_if_fail (dataset_location != NULL, NULL);
698
699 G_LOCK (g_dataset_global);
700 if (key_id && g_dataset_location_ht)
701 {
702 GDataset *dataset;
703
704 dataset = g_dataset_lookup (dataset_location);
705 if (dataset)
706 ret_data = g_data_set_internal (datalist: &dataset->datalist, key_id, NULL, new_destroy_func: (GDestroyNotify) 42, dataset);
707 }
708 G_UNLOCK (g_dataset_global);
709
710 return ret_data;
711}
712
713/**
714 * g_datalist_id_remove_no_notify: (skip)
715 * @datalist: a datalist.
716 * @key_id: the #GQuark identifying a data element.
717 *
718 * Removes an element, without calling its destroy notification
719 * function.
720 *
721 * Returns: (nullable): the data previously stored at @key_id,
722 * or %NULL if none.
723 **/
724/**
725 * g_datalist_remove_no_notify: (skip)
726 * @dl: a datalist.
727 * @k: the string identifying the data element.
728 *
729 * Removes an element, without calling its destroy notifier.
730 **/
731gpointer
732g_datalist_id_remove_no_notify (GData **datalist,
733 GQuark key_id)
734{
735 gpointer ret_data = NULL;
736
737 g_return_val_if_fail (datalist != NULL, NULL);
738
739 if (key_id)
740 ret_data = g_data_set_internal (datalist, key_id, NULL, new_destroy_func: (GDestroyNotify) 42, NULL);
741
742 return ret_data;
743}
744
745/**
746 * g_dataset_id_get_data:
747 * @dataset_location: (not nullable): the location identifying the dataset.
748 * @key_id: the #GQuark id to identify the data element.
749 *
750 * Gets the data element corresponding to a #GQuark.
751 *
752 * Returns: (transfer none) (nullable): the data element corresponding to
753 * the #GQuark, or %NULL if it is not found.
754 **/
755/**
756 * g_dataset_get_data:
757 * @l: the location identifying the dataset.
758 * @k: the string identifying the data element.
759 *
760 * Gets the data element corresponding to a string.
761 *
762 * Returns: (transfer none) (nullable): the data element corresponding to
763 * the string, or %NULL if it is not found.
764 **/
765gpointer
766g_dataset_id_get_data (gconstpointer dataset_location,
767 GQuark key_id)
768{
769 gpointer retval = NULL;
770
771 g_return_val_if_fail (dataset_location != NULL, NULL);
772
773 G_LOCK (g_dataset_global);
774 if (key_id && g_dataset_location_ht)
775 {
776 GDataset *dataset;
777
778 dataset = g_dataset_lookup (dataset_location);
779 if (dataset)
780 retval = g_datalist_id_get_data (datalist: &dataset->datalist, key_id);
781 }
782 G_UNLOCK (g_dataset_global);
783
784 return retval;
785}
786
787/**
788 * g_datalist_id_get_data:
789 * @datalist: a datalist.
790 * @key_id: the #GQuark identifying a data element.
791 *
792 * Retrieves the data element corresponding to @key_id.
793 *
794 * Returns: (transfer none) (nullable): the data element, or %NULL if
795 * it is not found.
796 */
797gpointer
798g_datalist_id_get_data (GData **datalist,
799 GQuark key_id)
800{
801 return g_datalist_id_dup_data (datalist, key_id, NULL, NULL);
802}
803
804/**
805 * GDuplicateFunc:
806 * @data: the data to duplicate
807 * @user_data: (closure): user data that was specified in
808 * g_datalist_id_dup_data()
809 *
810 * The type of functions that are used to 'duplicate' an object.
811 * What this means depends on the context, it could just be
812 * incrementing the reference count, if @data is a ref-counted
813 * object.
814 *
815 * Returns: a duplicate of data
816 */
817
818/**
819 * g_datalist_id_dup_data: (skip)
820 * @datalist: location of a datalist
821 * @key_id: the #GQuark identifying a data element
822 * @dup_func: (nullable) (scope call): function to duplicate the old value
823 * @user_data: (closure): passed as user_data to @dup_func
824 *
825 * This is a variant of g_datalist_id_get_data() which
826 * returns a 'duplicate' of the value. @dup_func defines the
827 * meaning of 'duplicate' in this context, it could e.g.
828 * take a reference on a ref-counted object.
829 *
830 * If the @key_id is not set in the datalist then @dup_func
831 * will be called with a %NULL argument.
832 *
833 * Note that @dup_func is called while the datalist is locked, so it
834 * is not allowed to read or modify the datalist.
835 *
836 * This function can be useful to avoid races when multiple
837 * threads are using the same datalist and the same key.
838 *
839 * Returns: (nullable): the result of calling @dup_func on the value
840 * associated with @key_id in @datalist, or %NULL if not set.
841 * If @dup_func is %NULL, the value is returned unmodified.
842 *
843 * Since: 2.34
844 */
845gpointer
846g_datalist_id_dup_data (GData **datalist,
847 GQuark key_id,
848 GDuplicateFunc dup_func,
849 gpointer user_data)
850{
851 gpointer val = NULL;
852 gpointer retval = NULL;
853 GData *d;
854 GDataElt *data, *data_end;
855
856 g_datalist_lock (datalist);
857
858 d = G_DATALIST_GET_POINTER (datalist);
859 if (d)
860 {
861 data = d->data;
862 data_end = data + d->len;
863 do
864 {
865 if (data->key == key_id)
866 {
867 val = data->data;
868 break;
869 }
870 data++;
871 }
872 while (data < data_end);
873 }
874
875 if (dup_func)
876 retval = dup_func (val, user_data);
877 else
878 retval = val;
879
880 g_datalist_unlock (datalist);
881
882 return retval;
883}
884
885/**
886 * g_datalist_id_replace_data: (skip)
887 * @datalist: location of a datalist
888 * @key_id: the #GQuark identifying a data element
889 * @oldval: (nullable): the old value to compare against
890 * @newval: (nullable): the new value to replace it with
891 * @destroy: (nullable): destroy notify for the new value
892 * @old_destroy: (out) (optional): destroy notify for the existing value
893 *
894 * Compares the member that is associated with @key_id in
895 * @datalist to @oldval, and if they are the same, replace
896 * @oldval with @newval.
897 *
898 * This is like a typical atomic compare-and-exchange
899 * operation, for a member of @datalist.
900 *
901 * If the previous value was replaced then ownership of the
902 * old value (@oldval) is passed to the caller, including
903 * the registered destroy notify for it (passed out in @old_destroy).
904 * Its up to the caller to free this as he wishes, which may
905 * or may not include using @old_destroy as sometimes replacement
906 * should not destroy the object in the normal way.
907 *
908 * Returns: %TRUE if the existing value for @key_id was replaced
909 * by @newval, %FALSE otherwise.
910 *
911 * Since: 2.34
912 */
913gboolean
914g_datalist_id_replace_data (GData **datalist,
915 GQuark key_id,
916 gpointer oldval,
917 gpointer newval,
918 GDestroyNotify destroy,
919 GDestroyNotify *old_destroy)
920{
921 gpointer val = NULL;
922 GData *d;
923 GDataElt *data, *data_end;
924
925 g_return_val_if_fail (datalist != NULL, FALSE);
926 g_return_val_if_fail (key_id != 0, FALSE);
927
928 if (old_destroy)
929 *old_destroy = NULL;
930
931 g_datalist_lock (datalist);
932
933 d = G_DATALIST_GET_POINTER (datalist);
934 if (d)
935 {
936 data = d->data;
937 data_end = data + d->len - 1;
938 while (data <= data_end)
939 {
940 if (data->key == key_id)
941 {
942 val = data->data;
943 if (val == oldval)
944 {
945 if (old_destroy)
946 *old_destroy = data->destroy;
947 if (newval != NULL)
948 {
949 data->data = newval;
950 data->destroy = destroy;
951 }
952 else
953 {
954 if (data != data_end)
955 *data = *data_end;
956 d->len--;
957
958 /* We don't bother to shrink, but if all data are now gone
959 * we at least free the memory
960 */
961 if (d->len == 0)
962 {
963 G_DATALIST_SET_POINTER (datalist, NULL);
964 g_free (mem: d);
965 }
966 }
967 }
968 break;
969 }
970 data++;
971 }
972 }
973
974 if (val == NULL && oldval == NULL && newval != NULL)
975 {
976 GData *old_d;
977
978 /* insert newval */
979 old_d = d;
980 if (d == NULL)
981 {
982 d = g_malloc (n_bytes: sizeof (GData));
983 d->len = 0;
984 d->alloc = 1;
985 }
986 else if (d->len == d->alloc)
987 {
988 d->alloc = d->alloc * 2;
989 d = g_realloc (mem: d, n_bytes: sizeof (GData) + (d->alloc - 1) * sizeof (GDataElt));
990 }
991 if (old_d != d)
992 G_DATALIST_SET_POINTER (datalist, d);
993
994 d->data[d->len].key = key_id;
995 d->data[d->len].data = newval;
996 d->data[d->len].destroy = destroy;
997 d->len++;
998 }
999
1000 g_datalist_unlock (datalist);
1001
1002 return val == oldval;
1003}
1004
1005/**
1006 * g_datalist_get_data:
1007 * @datalist: a datalist.
1008 * @key: the string identifying a data element.
1009 *
1010 * Gets a data element, using its string identifier. This is slower than
1011 * g_datalist_id_get_data() because it compares strings.
1012 *
1013 * Returns: (transfer none) (nullable): the data element, or %NULL if it
1014 * is not found.
1015 **/
1016gpointer
1017g_datalist_get_data (GData **datalist,
1018 const gchar *key)
1019{
1020 gpointer res = NULL;
1021 GData *d;
1022 GDataElt *data, *data_end;
1023
1024 g_return_val_if_fail (datalist != NULL, NULL);
1025
1026 g_datalist_lock (datalist);
1027
1028 d = G_DATALIST_GET_POINTER (datalist);
1029 if (d)
1030 {
1031 data = d->data;
1032 data_end = data + d->len;
1033 while (data < data_end)
1034 {
1035 if (g_strcmp0 (str1: g_quark_to_string (quark: data->key), str2: key) == 0)
1036 {
1037 res = data->data;
1038 break;
1039 }
1040 data++;
1041 }
1042 }
1043
1044 g_datalist_unlock (datalist);
1045
1046 return res;
1047}
1048
1049/**
1050 * GDataForeachFunc:
1051 * @key_id: the #GQuark id to identifying the data element.
1052 * @data: the data element.
1053 * @user_data: (closure): user data passed to g_dataset_foreach().
1054 *
1055 * Specifies the type of function passed to g_dataset_foreach(). It is
1056 * called with each #GQuark id and associated data element, together
1057 * with the @user_data parameter supplied to g_dataset_foreach().
1058 **/
1059
1060/**
1061 * g_dataset_foreach:
1062 * @dataset_location: (not nullable): the location identifying the dataset.
1063 * @func: (scope call): the function to call for each data element.
1064 * @user_data: (closure): user data to pass to the function.
1065 *
1066 * Calls the given function for each data element which is associated
1067 * with the given location. Note that this function is NOT thread-safe.
1068 * So unless @dataset_location can be protected from any modifications
1069 * during invocation of this function, it should not be called.
1070 *
1071 * @func can make changes to the dataset, but the iteration will not
1072 * reflect changes made during the g_dataset_foreach() call, other
1073 * than skipping over elements that are removed.
1074 **/
1075void
1076g_dataset_foreach (gconstpointer dataset_location,
1077 GDataForeachFunc func,
1078 gpointer user_data)
1079{
1080 GDataset *dataset;
1081
1082 g_return_if_fail (dataset_location != NULL);
1083 g_return_if_fail (func != NULL);
1084
1085 G_LOCK (g_dataset_global);
1086 if (g_dataset_location_ht)
1087 {
1088 dataset = g_dataset_lookup (dataset_location);
1089 G_UNLOCK (g_dataset_global);
1090 if (dataset)
1091 g_datalist_foreach (datalist: &dataset->datalist, func, user_data);
1092 }
1093 else
1094 {
1095 G_UNLOCK (g_dataset_global);
1096 }
1097}
1098
1099/**
1100 * g_datalist_foreach:
1101 * @datalist: a datalist.
1102 * @func: (scope call): the function to call for each data element.
1103 * @user_data: (closure): user data to pass to the function.
1104 *
1105 * Calls the given function for each data element of the datalist. The
1106 * function is called with each data element's #GQuark id and data,
1107 * together with the given @user_data parameter. Note that this
1108 * function is NOT thread-safe. So unless @datalist can be protected
1109 * from any modifications during invocation of this function, it should
1110 * not be called.
1111 *
1112 * @func can make changes to @datalist, but the iteration will not
1113 * reflect changes made during the g_datalist_foreach() call, other
1114 * than skipping over elements that are removed.
1115 **/
1116void
1117g_datalist_foreach (GData **datalist,
1118 GDataForeachFunc func,
1119 gpointer user_data)
1120{
1121 GData *d;
1122 guint i, j, len;
1123 GQuark *keys;
1124
1125 g_return_if_fail (datalist != NULL);
1126 g_return_if_fail (func != NULL);
1127
1128 d = G_DATALIST_GET_POINTER (datalist);
1129 if (d == NULL)
1130 return;
1131
1132 /* We make a copy of the keys so that we can handle it changing
1133 in the callback */
1134 len = d->len;
1135 keys = g_new (GQuark, len);
1136 for (i = 0; i < len; i++)
1137 keys[i] = d->data[i].key;
1138
1139 for (i = 0; i < len; i++)
1140 {
1141 /* A previous callback might have removed a later item, so always check that
1142 it still exists before calling */
1143 d = G_DATALIST_GET_POINTER (datalist);
1144
1145 if (d == NULL)
1146 break;
1147 for (j = 0; j < d->len; j++)
1148 {
1149 if (d->data[j].key == keys[i]) {
1150 func (d->data[i].key, d->data[i].data, user_data);
1151 break;
1152 }
1153 }
1154 }
1155 g_free (mem: keys);
1156}
1157
1158/**
1159 * g_datalist_init: (skip)
1160 * @datalist: a pointer to a pointer to a datalist.
1161 *
1162 * Resets the datalist to %NULL. It does not free any memory or call
1163 * any destroy functions.
1164 **/
1165void
1166g_datalist_init (GData **datalist)
1167{
1168 g_return_if_fail (datalist != NULL);
1169
1170 g_atomic_pointer_set (datalist, NULL);
1171}
1172
1173/**
1174 * g_datalist_set_flags:
1175 * @datalist: pointer to the location that holds a list
1176 * @flags: the flags to turn on. The values of the flags are
1177 * restricted by %G_DATALIST_FLAGS_MASK (currently
1178 * 3; giving two possible boolean flags).
1179 * A value for @flags that doesn't fit within the mask is
1180 * an error.
1181 *
1182 * Turns on flag values for a data list. This function is used
1183 * to keep a small number of boolean flags in an object with
1184 * a data list without using any additional space. It is
1185 * not generally useful except in circumstances where space
1186 * is very tight. (It is used in the base #GObject type, for
1187 * example.)
1188 *
1189 * Since: 2.8
1190 **/
1191void
1192g_datalist_set_flags (GData **datalist,
1193 guint flags)
1194{
1195 g_return_if_fail (datalist != NULL);
1196 g_return_if_fail ((flags & ~G_DATALIST_FLAGS_MASK) == 0);
1197
1198 g_atomic_pointer_or (datalist, (gsize)flags);
1199}
1200
1201/**
1202 * g_datalist_unset_flags:
1203 * @datalist: pointer to the location that holds a list
1204 * @flags: the flags to turn off. The values of the flags are
1205 * restricted by %G_DATALIST_FLAGS_MASK (currently
1206 * 3: giving two possible boolean flags).
1207 * A value for @flags that doesn't fit within the mask is
1208 * an error.
1209 *
1210 * Turns off flag values for a data list. See g_datalist_unset_flags()
1211 *
1212 * Since: 2.8
1213 **/
1214void
1215g_datalist_unset_flags (GData **datalist,
1216 guint flags)
1217{
1218 g_return_if_fail (datalist != NULL);
1219 g_return_if_fail ((flags & ~G_DATALIST_FLAGS_MASK) == 0);
1220
1221 g_atomic_pointer_and (datalist, ~(gsize)flags);
1222}
1223
1224/**
1225 * g_datalist_get_flags:
1226 * @datalist: pointer to the location that holds a list
1227 *
1228 * Gets flags values packed in together with the datalist.
1229 * See g_datalist_set_flags().
1230 *
1231 * Returns: the flags of the datalist
1232 *
1233 * Since: 2.8
1234 **/
1235guint
1236g_datalist_get_flags (GData **datalist)
1237{
1238 g_return_val_if_fail (datalist != NULL, 0);
1239
1240 return G_DATALIST_GET_FLAGS (datalist); /* atomic macro */
1241}
1242
1243/* HOLDS: g_dataset_global_lock */
1244static void
1245g_data_initialize (void)
1246{
1247 g_return_if_fail (g_dataset_location_ht == NULL);
1248
1249 g_dataset_location_ht = g_hash_table_new (hash_func: g_direct_hash, NULL);
1250 g_dataset_cached = NULL;
1251}
1252

source code of gtk/subprojects/glib/glib/gdataset.c