Mercurial > pidgin
comparison src/stringref.h @ 7763:dc79649b829d
[gaim-migrate @ 8408]
This is an implementation of immutable, reference-counted strings. It
is exceedingly trivial, I have no idea why I didn't do this long
ago... PLEASE use these anywhere you pass around strings that may be
stuck in multiple places; I'm not sure that it will save us too much
heap holistically, but it should prevent having to make a hojillion
twenty-byte allocations and free them immediately.
committer: Tailor Script <tailor@pidgin.im>
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Fri, 05 Dec 2003 16:56:03 +0000 |
parents | |
children | 1f4005fcd872 |
comparison
equal
deleted
inserted
replaced
7762:5f1908a49c78 | 7763:dc79649b829d |
---|---|
1 /** | |
2 * @file stringref.h Reference-counted immutable strings | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Copyright (C) 2003 Ethan Blanton <elb@elitists.net> | |
8 * | |
9 * This program is free software; you can redistribute it and/or modify | |
10 * it under the terms of the GNU General Public License as published by | |
11 * the Free Software Foundation; either version 2 of the License, or | |
12 * (at your option) any later version. | |
13 * | |
14 * This program is distributed in the hope that it will be useful, | |
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 * GNU General Public License for more details. | |
18 * | |
19 * You should have received a copy of the GNU General Public License | |
20 * along with this program; if not, write to the Free Software | |
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
22 * | |
23 */ | |
24 | |
25 #ifndef _GAIM_STRINGREF_H_ | |
26 #define _GAIM_STRINGREF_H_ | |
27 | |
28 /** | |
29 * @note For this structure to be useful, the string contained within | |
30 * it must be immutable -- for this reason, do _not_ access it | |
31 * directly! | |
32 */ | |
33 typedef struct _GaimStringref { | |
34 int ref; | |
35 char value[0]; | |
36 } GaimStringref; | |
37 | |
38 /** | |
39 * Creates an immutable reference-counted string object. The newly | |
40 * created object will have a reference count of 1. | |
41 * | |
42 * @param value This will be the value of the string; it will be | |
43 * duplicated. | |
44 * | |
45 * @return A newly allocated string reference object. | |
46 */ | |
47 GaimStringref *gaim_stringref_new(const char *value); | |
48 | |
49 /** | |
50 * Increase the reference count of the given stringref. | |
51 * | |
52 * @param stringref String to be referenced. | |
53 * | |
54 * @return A pointer to the referenced string. | |
55 */ | |
56 GaimStringref *gaim_stringref_ref(GaimStringref *stringref); | |
57 | |
58 /** | |
59 * Decrease the reference count of the given stringref. If this | |
60 * reference count reaches zero, the stringref will be freed; thus | |
61 * you MUST NOT use this string after dereferencing it. | |
62 * | |
63 * @param stringref String to be dereferenced. | |
64 */ | |
65 void gaim_stringref_unref(GaimStringref *stringref); | |
66 | |
67 /** | |
68 * Retrieve the value of a stringref. | |
69 * | |
70 * @note This value should not be cached or stored in a local variable. | |
71 * While there is nothing inherently incorrect about doing so, it | |
72 * is easy to forget that the cached value is in fact a | |
73 * reference-counted object and accidentally use it after | |
74 * dereferencing. This is more problematic for a reference- | |
75 * counted object than a heap-allocated object, as it may seem to | |
76 * be valid or invalid nondeterministically based on how many | |
77 * other references to it exist. | |
78 * | |
79 * @param stringref String reference from which to retrieve the value. | |
80 * | |
81 * @return The contents of the string reference. | |
82 */ | |
83 const char *gaim_stringref_value(GaimStringref *stringref); | |
84 | |
85 #endif /* _GAIM_STRINGREF_H_ */ |