glib/glib/gquark.c
Matthias Clasen e7fd3de86d Eradicate links and xrefs
These are all replaced by markdown ref links.
2014-02-08 12:26:56 -05:00

360 lines
9.3 KiB
C

/* GLIB - Library of useful routines for C programming
* Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
* Copyright (C) 1998 Tim Janik
*
* gquark.c: Functions for dealing with quarks and interned strings
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* Modified by the GLib Team and others 1997-2000. See the AUTHORS
* file for a list of people on the GLib Team. See the ChangeLog
* files for a list of changes. These files are distributed with
* GLib at ftp://ftp.gtk.org/pub/gtk/.
*/
/*
* MT safe
*/
#include "config.h"
#include <string.h>
#include "gslice.h"
#include "ghash.h"
#include "gquark.h"
#include "gstrfuncs.h"
#include "gthread.h"
#include "gtestutils.h"
#include "glib_trace.h"
#define QUARK_BLOCK_SIZE 2048
#define QUARK_STRING_BLOCK_SIZE (4096 - sizeof (gsize))
static inline GQuark quark_new (gchar *string);
G_LOCK_DEFINE_STATIC (quark_global);
static GHashTable *quark_ht = NULL;
static gchar **quarks = NULL;
static gint quark_seq_id = 0;
static gchar *quark_block = NULL;
static gint quark_block_offset = 0;
/**
* SECTION:quarks
* @title: Quarks
* @short_description: a 2-way association between a string and a
* unique integer identifier
*
* Quarks are associations between strings and integer identifiers.
* Given either the string or the #GQuark identifier it is possible to
* retrieve the other.
*
* Quarks are used for both [datasets][glib-Datasets] and
* [keyed data lists][glib-Keyed-Data-Lists].
*
* To create a new quark from a string, use g_quark_from_string() or
* g_quark_from_static_string().
*
* To find the string corresponding to a given #GQuark, use
* g_quark_to_string().
*
* To find the #GQuark corresponding to a given string, use
* g_quark_try_string().
*
* Another use for the string pool maintained for the quark functions
* is string interning, using g_intern_string() or
* g_intern_static_string(). An interned string is a canonical
* representation for a string. One important advantage of interned
* strings is that they can be compared for equality by a simple
* pointer comparison, rather than using strcmp().
*/
/**
* GQuark:
*
* A GQuark is a non-zero integer which uniquely identifies a
* particular string. A GQuark value of zero is associated to %NULL.
*/
/**
* G_DEFINE_QUARK:
* @QN: the name to return a #GQuark for
* @q_n: prefix for the function name
*
* A convenience macro which defines a function returning the
* #GQuark for the name @QN. The function will be named
* @q_n_quark().
*
* Note that the quark name will be stringified automatically
* in the macro, so you shouldn't use double quotes.
*
* Since: 2.34
*/
/**
* g_quark_try_string:
* @string: (allow-none): a string
*
* Gets the #GQuark associated with the given string, or 0 if string is
* %NULL or it has no associated #GQuark.
*
* If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string().
*
* Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it
*/
GQuark
g_quark_try_string (const gchar *string)
{
GQuark quark = 0;
if (string == NULL)
return 0;
G_LOCK (quark_global);
if (quark_ht)
quark = GPOINTER_TO_UINT (g_hash_table_lookup (quark_ht, string));
G_UNLOCK (quark_global);
return quark;
}
/* HOLDS: quark_global_lock */
static char *
quark_strdup (const gchar *string)
{
gchar *copy;
gsize len;
len = strlen (string) + 1;
/* For strings longer than half the block size, fall back
to strdup so that we fill our blocks at least 50%. */
if (len > QUARK_STRING_BLOCK_SIZE / 2)
return g_strdup (string);
if (quark_block == NULL ||
QUARK_STRING_BLOCK_SIZE - quark_block_offset < len)
{
quark_block = g_malloc (QUARK_STRING_BLOCK_SIZE);
quark_block_offset = 0;
}
copy = quark_block + quark_block_offset;
memcpy (copy, string, len);
quark_block_offset += len;
return copy;
}
/* HOLDS: quark_global_lock */
static inline GQuark
quark_from_string (const gchar *string,
gboolean duplicate)
{
GQuark quark = 0;
if (quark_ht)
quark = GPOINTER_TO_UINT (g_hash_table_lookup (quark_ht, string));
if (!quark)
{
quark = quark_new (duplicate ? quark_strdup (string) : (gchar *)string);
TRACE(GLIB_QUARK_NEW(string, quark));
}
return quark;
}
/**
* g_quark_from_string:
* @string: (allow-none): a string
*
* Gets the #GQuark identifying the given string. If the string does
* not currently have an associated #GQuark, a new #GQuark is created,
* using a copy of the string.
*
* Returns: the #GQuark identifying the string, or 0 if @string is %NULL
*/
GQuark
g_quark_from_string (const gchar *string)
{
GQuark quark;
if (!string)
return 0;
G_LOCK (quark_global);
quark = quark_from_string (string, TRUE);
G_UNLOCK (quark_global);
return quark;
}
/**
* g_quark_from_static_string:
* @string: (allow-none): a string
*
* Gets the #GQuark identifying the given (static) string. If the
* string does not currently have an associated #GQuark, a new #GQuark
* is created, linked to the given string.
*
* Note that this function is identical to g_quark_from_string() except
* that if a new #GQuark is created the string itself is used rather
* than a copy. This saves memory, but can only be used if the string
* will continue to exist until the program terminates. It can be used
* with statically allocated strings in the main program, but not with
* statically allocated memory in dynamically loaded modules, if you
* expect to ever unload the module again (e.g. do not use this
* function in GTK+ theme engines).
*
* Returns: the #GQuark identifying the string, or 0 if @string is %NULL
*/
GQuark
g_quark_from_static_string (const gchar *string)
{
GQuark quark;
if (!string)
return 0;
G_LOCK (quark_global);
quark = quark_from_string (string, FALSE);
G_UNLOCK (quark_global);
return quark;
}
/**
* g_quark_to_string:
* @quark: a #GQuark.
*
* Gets the string associated with the given #GQuark.
*
* Returns: the string associated with the #GQuark
*/
const gchar *
g_quark_to_string (GQuark quark)
{
gchar* result = NULL;
gchar **strings;
gint seq_id;
seq_id = g_atomic_int_get (&quark_seq_id);
strings = g_atomic_pointer_get (&quarks);
if (quark < seq_id)
result = strings[quark];
return result;
}
/* HOLDS: g_quark_global_lock */
static inline GQuark
quark_new (gchar *string)
{
GQuark quark;
gchar **quarks_new;
if (quark_seq_id % QUARK_BLOCK_SIZE == 0)
{
quarks_new = g_new (gchar*, quark_seq_id + QUARK_BLOCK_SIZE);
if (quark_seq_id != 0)
memcpy (quarks_new, quarks, sizeof (char *) * quark_seq_id);
memset (quarks_new + quark_seq_id, 0, sizeof (char *) * QUARK_BLOCK_SIZE);
/* This leaks the old quarks array. Its unfortunate, but it allows
* us to do lockless lookup of the arrays, and there shouldn't be that
* many quarks in an app
*/
g_atomic_pointer_set (&quarks, quarks_new);
}
if (!quark_ht)
{
g_assert (quark_seq_id == 0);
quark_ht = g_hash_table_new (g_str_hash, g_str_equal);
quarks[quark_seq_id] = NULL;
g_atomic_int_inc (&quark_seq_id);
}
quark = quark_seq_id;
g_atomic_pointer_set (&quarks[quark], string);
g_hash_table_insert (quark_ht, string, GUINT_TO_POINTER (quark));
g_atomic_int_inc (&quark_seq_id);
return quark;
}
/**
* g_intern_string:
* @string: (allow-none): a string
*
* Returns a canonical representation for @string. Interned strings
* can be compared for equality by comparing the pointers, instead of
* using strcmp().
*
* Returns: a canonical representation for the string
*
* Since: 2.10
*/
const gchar *
g_intern_string (const gchar *string)
{
const gchar *result;
GQuark quark;
if (!string)
return NULL;
G_LOCK (quark_global);
quark = quark_from_string (string, TRUE);
result = quarks[quark];
G_UNLOCK (quark_global);
return result;
}
/**
* g_intern_static_string:
* @string: (allow-none): a static string
*
* Returns a canonical representation for @string. Interned strings
* can be compared for equality by comparing the pointers, instead of
* using strcmp(). g_intern_static_string() does not copy the string,
* therefore @string must not be freed or modified.
*
* Returns: a canonical representation for the string
*
* Since: 2.10
*/
const gchar *
g_intern_static_string (const gchar *string)
{
GQuark quark;
const gchar *result;
if (!string)
return NULL;
G_LOCK (quark_global);
quark = quark_from_string (string, FALSE);
result = quarks[quark];
G_UNLOCK (quark_global);
return result;
}