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