glib/gdataset.c

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