File: grefstring.c

package info (click to toggle)
glib2.0 2.58.3-2+deb10u2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, buster-backports, buster-proposed-updates, sid
  • size: 48,956 kB
  • sloc: ansic: 452,656; xml: 16,781; python: 6,149; makefile: 3,776; sh: 1,499; perl: 1,140; cpp: 9
file content (302 lines) | stat: -rw-r--r-- 8,699 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
/* grefstring.c: Reference counted strings
 *
 * Copyright 2018  Emmanuele Bassi
 *
 * 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.1 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/>.
 */

/**
 * SECTION:refstring
 * @Title: Reference counted strings
 * @Short_description: Strings with reference counted memory management
 *
 * Reference counted strings are normal C strings that have been augmented
 * with a reference counter to manage their resources. You allocate a new
 * reference counted string and acquire and release references as needed,
 * instead of copying the string among callers; when the last reference on
 * the string is released, the resources allocated for it are freed.
 *
 * Typically, reference counted strings can be used when parsing data from
 * files and storing them into data structures that are passed to various
 * callers:
 *
 * |[<!-- language="C" -->
 * PersonDetails *
 * person_details_from_data (const char *data)
 * {
 *   // Use g_autoptr() to simplify error cases
 *   g_autoptr(GRefString) full_name = NULL;
 *   g_autoptr(GRefString) address =  NULL;
 *   g_autoptr(GRefString) city = NULL;
 *   g_autoptr(GRefString) state = NULL;
 *   g_autoptr(GRefString) zip_code = NULL;
 *
 *   // parse_person_details() is defined elsewhere; returns refcounted strings
 *   if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
 *     return NULL;
 *
 *   if (!validate_zip_code (zip_code))
 *     return NULL;
 *
 *   // add_address_to_cache() and add_full_name_to_cache() are defined
 *   // elsewhere; they add strings to various caches, using refcounted
 *   // strings to avoid copying data over and over again
 *   add_address_to_cache (address, city, state, zip_code);
 *   add_full_name_to_cache (full_name);
 *
 *   // person_details_new() is defined elsewhere; it takes a reference
 *   // on each string
 *   PersonDetails *res = person_details_new (full_name,
 *                                            address,
 *                                            city,
 *                                            state,
 *                                            zip_code);
 *
 *   return res;
 * }
 * ]|
 *
 * In the example above, we have multiple functions taking the same strings
 * for different uses; with typical C strings, we'd have to copy the strings
 * every time the life time rules of the data differ from the life time of
 * the string parsed from the original buffer. With reference counted strings,
 * each caller can take a reference on the data, and keep it as long as it
 * needs to own the string.
 *
 * Reference counted strings can also be "interned" inside a global table
 * owned by GLib; while an interned string has at least a reference, creating
 * a new interned reference counted string with the same contents will return
 * a reference to the existing string instead of creating a new reference
 * counted string instance. Once the string loses its last reference, it will
 * be automatically removed from the global interned strings table.
 *
 * Since: 2.58
 */

#include "config.h"

#include "grefstring.h"

#include "ghash.h"
#include "gmessages.h"
#include "grcbox.h"
#include "gthread.h"

#include <string.h>

/* A global table of refcounted strings; the hash table does not own
 * the strings, just a pointer to them. Strings are interned as long
 * as they are alive; once their reference count drops to zero, they
 * are removed from the table
 */
G_LOCK_DEFINE_STATIC (interned_ref_strings);
static GHashTable *interned_ref_strings;

/**
 * g_ref_string_new:
 * @str: (not nullable): a NUL-terminated string
 *
 * Creates a new reference counted string and copies the contents of @str
 * into it.
 *
 * Returns: (transfer full) (not nullable): the newly created reference counted string
 *
 * Since: 2.58
 */
char *
g_ref_string_new (const char *str)
{
  char *res;
  gsize len;

  g_return_val_if_fail (str != NULL, NULL);
  
  len = strlen (str);
  
  res = (char *) g_atomic_rc_box_dup (sizeof (char) * len + 1, str);

  return res;
}

/**
 * g_ref_string_new_len:
 * @str: (not nullable): a string
 * @len: length of @str to use, or -1 if @str is nul-terminated
 *
 * Creates a new reference counted string and copies the contents of @str
 * into it, up to @len bytes.
 *
 * Since this function does not stop at nul bytes, it is the caller's
 * responsibility to ensure that @str has at least @len addressable bytes.
 *
 * Returns: (transfer full) (not nullable): the newly created reference counted string
 *
 * Since: 2.58
 */
char *
g_ref_string_new_len (const char *str, gssize len)
{
  char *res;

  g_return_val_if_fail (str != NULL, NULL);

  if (len < 0)
    return g_ref_string_new (str);

  /* allocate then copy as str[len] may not be readable */
  res = (char *) g_atomic_rc_box_alloc ((gsize) len + 1);
  memcpy (res, str, len);
  res[len] = '\0';

  return res;
}

/* interned_str_equal: variant of g_str_equal() that compares
 * pointers as well as contents; this avoids running strcmp()
 * on arbitrarily long strings, as it's more likely to have
 * g_ref_string_new_intern() being called on the same refcounted
 * string instance, than on a different string with the same
 * contents
 */
static gboolean
interned_str_equal (gconstpointer v1,
                    gconstpointer v2)
{
  const char *str1 = v1;
  const char *str2 = v2;

  if (v1 == v2)
    return TRUE;

  return strcmp (str1, str2) == 0;
}

/**
 * g_ref_string_new_intern:
 * @str: (not nullable): a NUL-terminated string
 *
 * Creates a new reference counted string and copies the content of @str
 * into it.
 *
 * If you call this function multiple times with the same @str, or with
 * the same contents of @str, it will return a new reference, instead of
 * creating a new string.
 *
 * Returns: (transfer full) (not nullable): the newly created reference
 *   counted string, or a new reference to an existing string
 *
 * Since: 2.58
 */
char *
g_ref_string_new_intern (const char *str)
{
  char *res;

  g_return_val_if_fail (str != NULL, NULL);

  G_LOCK (interned_ref_strings);

  if (G_UNLIKELY (interned_ref_strings == NULL))
    interned_ref_strings = g_hash_table_new (g_str_hash, interned_str_equal);

  res = g_hash_table_lookup (interned_ref_strings, str);
  if (res != NULL)
    {
      /* We acquire the reference while holding the lock, to
       * avoid a potential race between releasing the lock on
       * the hash table and another thread releasing the reference
       * on the same string
       */
      g_atomic_rc_box_acquire (res);
      G_UNLOCK (interned_ref_strings);
      return res;
    }

  res = g_ref_string_new (str);
  g_hash_table_add (interned_ref_strings, res);
  G_UNLOCK (interned_ref_strings);

  return res;
}

/**
 * g_ref_string_acquire:
 * @str: a reference counted string
 *
 * Acquires a reference on a string.
 *
 * Returns: the given string, with its reference count increased
 *
 * Since: 2.58
 */
char *
g_ref_string_acquire (char *str)
{
  g_return_val_if_fail (str != NULL, NULL);

  return g_atomic_rc_box_acquire (str);
}

static void
remove_if_interned (gpointer data)
{
  char *str = data;

  G_LOCK (interned_ref_strings);

  if (G_LIKELY (interned_ref_strings != NULL))
    {
      g_hash_table_remove (interned_ref_strings, str);

      if (g_hash_table_size (interned_ref_strings) == 0)
        g_clear_pointer (&interned_ref_strings, g_hash_table_destroy);
    }

  G_UNLOCK (interned_ref_strings);
}

/**
 * g_ref_string_release:
 * @str: a reference counted string
 *
 * Releases a reference on a string; if it was the last reference, the
 * resources allocated by the string are freed as well.
 *
 * Since: 2.58
 */
void
g_ref_string_release (char *str)
{
  g_return_if_fail (str != NULL);

  g_atomic_rc_box_release_full (str, remove_if_interned);
}

/**
 * g_ref_string_length:
 * @str: a reference counted string
 *
 * Retrieves the length of @str.
 *
 * Returns: the length of the given string, in bytes
 *
 * Since: 2.58
 */
gsize
g_ref_string_length (char *str)
{
  g_return_val_if_fail (str != NULL, 0);

  return g_atomic_rc_box_get_size (str) - 1;
}