annotate src/stringref.h @ 13374:14d1892e0932

[gaim-migrate @ 15747] Fix the showstopper bug about autoreconnect being too aggressive "If you try to connect to an account and it fails, switching your global status to Offline will not prevent the autoreconnect from trying to re-connect" committer: Tailor Script <tailor@pidgin.im>
author Mark Doliner <mark@kingant.net>
date Thu, 02 Mar 2006 05:58:21 +0000
parents db62420a53a2
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
1 /**
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
2 * @file stringref.h Reference-counted immutable strings
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
3 * @ingroup core
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
4 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
5 * gaim
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
6 *
8046
fa6395637e2c [gaim-migrate @ 8730]
Sean Egan <seanegan@gmail.com>
parents: 7791
diff changeset
7 * Gaim is the legal property of its developers, whose names are too numerous
fa6395637e2c [gaim-migrate @ 8730]
Sean Egan <seanegan@gmail.com>
parents: 7791
diff changeset
8 * to list here. Please refer to the COPYRIGHT file distributed with this
fa6395637e2c [gaim-migrate @ 8730]
Sean Egan <seanegan@gmail.com>
parents: 7791
diff changeset
9 * source distribution.
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
10 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
11 * This program is free software; you can redistribute it and/or modify
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
12 * it under the terms of the GNU General Public License as published by
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
13 * the Free Software Foundation; either version 2 of the License, or
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
14 * (at your option) any later version.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
15 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
16 * This program is distributed in the hope that it will be useful,
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
19 * GNU General Public License for more details.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
20 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
21 * You should have received a copy of the GNU General Public License
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
22 * along with this program; if not, write to the Free Software
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
24 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
25 */
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
26 #ifndef _GAIM_STRINGREF_H_
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
27 #define _GAIM_STRINGREF_H_
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
28
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
29 /**
7786
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
30 * The internal representation of a stringref.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
31 *
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
32 * @note For this structure to be useful, the string contained within
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
33 * it must be immutable -- for this reason, do _not_ access it
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
34 * directly!
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
35 */
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
36 typedef struct _GaimStringref {
7791
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
37 guint32 ref; /**< The reference count of this string.
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
38 * Note that reference counts are only
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
39 * 31 bits, and the high-order bit
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
40 * indicates whether this string is up
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
41 * for GC at the next idle handler...
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
42 * But you aren't going to touch this
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
43 * anyway, right? */
8072
ceb88c0a1abb [gaim-migrate @ 8770]
Nathan Walp <nwalp@pidgin.im>
parents: 8046
diff changeset
44 char value[1]; /**< The string contained in this ref.
7791
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
45 * Notice that it is simply "hanging
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
46 * off the end" of the ref ... this
21be2d9e8399 [gaim-migrate @ 8437]
Nathan Walp <nwalp@pidgin.im>
parents: 7786
diff changeset
47 * is to save an allocation. */
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
48 } GaimStringref;
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
49
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
50 /**
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
51 * Creates an immutable reference-counted string object. The newly
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
52 * created object will have a reference count of 1.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
53 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
54 * @param value This will be the value of the string; it will be
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
55 * duplicated.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
56 *
7767
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
57 * @return A newly allocated string reference object with a refcount
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
58 * of 1.
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
59 */
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
60 GaimStringref *gaim_stringref_new(const char *value);
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
61
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
62 /**
7786
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
63 * Creates an immutable reference-counted string object. The newly
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
64 * created object will have a reference count of zero, and if it is
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
65 * not referenced before the next iteration of the mainloop it will
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
66 * be freed at that time.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
67 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
68 * @param value This will be the value of the string; it will be
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
69 * duplicated.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
70 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
71 * @return A newly allocated string reference object with a refcount
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
72 * of zero.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
73 */
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
74 GaimStringref *gaim_stringref_new_noref(const char *value);
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
75
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
76 /**
7767
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
77 * Creates an immutable reference-counted string object from a printf
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
78 * format specification and arguments. The created object will have a
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
79 * reference count of 1.
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
80 *
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
81 * @param format A printf-style format specification.
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
82 *
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
83 * @return A newly allocated string reference object with a refcount
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
84 * of 1.
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
85 */
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
86 GaimStringref *gaim_stringref_printf(const char *format, ...);
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
87
1f4005fcd872 [gaim-migrate @ 8412]
Ethan Blanton <elb@pidgin.im>
parents: 7763
diff changeset
88 /**
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
89 * Increase the reference count of the given stringref.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
90 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
91 * @param stringref String to be referenced.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
92 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
93 * @return A pointer to the referenced string.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
94 */
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
95 GaimStringref *gaim_stringref_ref(GaimStringref *stringref);
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
96
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
97 /**
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
98 * Decrease the reference count of the given stringref. If this
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
99 * reference count reaches zero, the stringref will be freed; thus
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
100 * you MUST NOT use this string after dereferencing it.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
101 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
102 * @param stringref String to be dereferenced.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
103 */
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
104 void gaim_stringref_unref(GaimStringref *stringref);
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
105
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
106 /**
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
107 * Retrieve the value of a stringref.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
108 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
109 * @note This value should not be cached or stored in a local variable.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
110 * While there is nothing inherently incorrect about doing so, it
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
111 * is easy to forget that the cached value is in fact a
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
112 * reference-counted object and accidentally use it after
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
113 * dereferencing. This is more problematic for a reference-
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
114 * counted object than a heap-allocated object, as it may seem to
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
115 * be valid or invalid nondeterministically based on how many
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
116 * other references to it exist.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
117 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
118 * @param stringref String reference from which to retrieve the value.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
119 *
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
120 * @return The contents of the string reference.
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
121 */
7768
4e5c48ea9478 [gaim-migrate @ 8413]
Ethan Blanton <elb@pidgin.im>
parents: 7767
diff changeset
122 const char *gaim_stringref_value(const GaimStringref *stringref);
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
123
7786
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
124 /**
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
125 * Compare two stringrefs for string equality. This returns the same
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
126 * value as strcmp would, where <0 indicates that s1 is "less than" s2
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
127 * in the ASCII lexicography, 0 indicates equality, etc.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
128 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
129 * @param s1 The reference string.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
130 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
131 * @param s2 The string to compare against the reference.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
132 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
133 * @return An ordering indication on s1 and s2.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
134 */
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
135 int gaim_stringref_cmp(const GaimStringref *s1, const GaimStringref *s2);
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
136
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
137 /**
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
138 * Find the length of the string inside a stringref.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
139 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
140 * @param stringref The string in whose length we are interested.
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
141 *
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
142 * @return The length of the string in stringref
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
143 */
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
144 size_t gaim_stringref_len(const GaimStringref *stringref);
203a18e56dc6 [gaim-migrate @ 8431]
Ethan Blanton <elb@pidgin.im>
parents: 7768
diff changeset
145
7763
dc79649b829d [gaim-migrate @ 8408]
Ethan Blanton <elb@pidgin.im>
parents:
diff changeset
146 #endif /* _GAIM_STRINGREF_H_ */