1/*
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/* IOSymbol.h created by gvdl on Fri 1998-10-30 */
29/* OSSymbol must be created through the factory methods and thus is not subclassable. */
30
31#ifndef _OS_OSSYMBOL_H
32#define _OS_OSSYMBOL_H
33
34#include <libkern/c++/OSString.h>
35
36/*!
37 * @header
38 *
39 * @abstract
40 * This header declares the OSSymbol container class.
41 */
42
43// xx-review: OSSymbol does not override setChar
44
45/*!
46 * @class OSSymbol
47 *
48 * @abstract
49 * OSSymbol wraps a C string in a unique C++ object
50 * for use as keys in Libkern collections.
51 *
52 * @discussion
53 * OSSymbol is a container class for managing uniqued strings,
54 * for example, those used as dictionary keys.
55 * Its static instance-creation functions check
56 * for an existing instance of OSSymbol
57 * with the requested C string value before creating a new object.
58 * If an instance already exists in the pool of unique symbols,
59 * its reference count is incremented
60 * and the existing instance is returned.
61 *
62 * While OSSymbol provides for uniquing of a given string value,
63 * it makes no effort to enforce immutability of that value.
64 * Altering the contents of an OSSymbol should be avoided.
65 *
66 * <b>Use Restrictions</b>
67 *
68 * With very few exceptions in the I/O Kit, all Libkern-based C++
69 * classes, functions, and macros are <b>unsafe</b>
70 * to use in a primary interrupt context.
71 * Consult the I/O Kit documentation related to primary interrupts
72 * for more information.
73 *
74 * OSSymbol provides no concurrency protection;
75 * it's up to the usage context to provide any protection necessary.
76 * Some portions of the I/O Kit, such as
77 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
78 * handle synchronization via defined member functions for setting
79 * properties.
80 */
81class OSSymbol : public OSString
82{
83 friend class OSSymbolPool;
84
85 OSDeclareAbstractStructors(OSSymbol)
86
87private:
88
89 static void initialize();
90
91 /*!
92 * @function initWithString
93 *
94 * @abstract
95 * Overridden to prevent creation of duplicate symbols.
96 *
97 * @param aString Unused.
98 *
99 * @result
100 * <code>false</code>.
101 *
102 * @discussion
103 * Overrides OSString's implementation to prevent creation
104 * of distinct OSSymbols with the same string value.
105 */
106 virtual bool initWithString(const OSString * aString) APPLE_KEXT_OVERRIDE;
107
108
109 /*!
110 * @function initWithCString
111 *
112 * @abstract
113 * Overridden to prevent creation of duplicate symbols.
114 *
115 * @param cString Unused.
116 *
117 * @result
118 * <code>false</code>.
119 *
120 * @discussion
121 * Overrides OSString's implementation to prevent creation
122 * of distinct OSSymbols with the same string value.
123 */
124 virtual bool initWithCString(const char * cString) APPLE_KEXT_OVERRIDE;
125
126
127 /*!
128 * @function initWithCStringNoCopy
129 *
130 * @abstract
131 * Overridden to prevent creation of duplicate symbols.
132 *
133 * @param cString Unused.
134 *
135 * @result
136 * <code>false</code>.
137 *
138 * @discussion
139 * Overrides OSString's implementation to prevent creation
140 * of distinct OSSymbols with the same string value.
141 */
142 virtual bool initWithCStringNoCopy(const char *cString) APPLE_KEXT_OVERRIDE;
143
144protected:
145
146// xx-review: should we just omit this from headerdoc?
147 /*!
148 * @function taggedRelease
149 *
150 * @abstract
151 * Overrides
152 * <code>@link
153 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
154 * OSObject::taggedRelease(const void *, const int)@/link</code>
155 * to synchronize with the symbol pool.
156 *
157 * @param tag Used for tracking collection references.
158 * @param freeWhen If decrementing the reference count makes it
159 * >= <code>freeWhen</code>, the object is immediately freed.
160 *
161 * @discussion
162 * Because OSSymbol shares instances, the reference-counting functions
163 * must synchronize access to the class-internal tables
164 * used to track those instances.
165 */
166 virtual void taggedRelease(
167 const void * tag,
168 const int freeWhen) const APPLE_KEXT_OVERRIDE;
169
170
171// xx-review: should we just omit this from headerdoc?
172 /*!
173 * @function free
174 *
175 * @abstract
176 * Overrides
177 * <code>@link
178 * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
179 * OSObject::free@/link</code>
180 * to synchronize with the symbol pool.
181 *
182 * @discussion
183 * Because OSSymbol shares instances, the reference-counting functions
184 * must synchronize access to the class-internal tables
185 * used to track those instances.
186 */
187 virtual void free() APPLE_KEXT_OVERRIDE;
188
189public:
190
191// xx-review: should we just omit this from headerdoc?
192 /*!
193 * @function taggedRelease
194 *
195 * @abstract
196 * Overrides
197 * <code>@link
198 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
199 * OSObject::taggedRelease(const void *)@/link</code>
200 * to synchronize with the symbol pool.
201 *
202 * @param tag Used for tracking collection references.
203 *
204 * @discussion
205 * Because OSSymbol shares instances, the reference-counting functions
206 * must synchronize access to the class-internal tables
207 * used to track those instances.
208 */
209
210 /* Original note (not for headerdoc):
211 * The C++ language has forced me to override this method
212 * even though I have implemented it as
213 * <code>{ super::taggedRelease(tag) }</code>.
214 * It seems that C++ is confused about the appearance of the protected
215 * taggedRelease with 2 parameters and refuses to only inherit one function.
216 * See
217 * <code>@link
218 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
219 * OSObject::taggedRelease(const void *, const int)@/link</code>.
220 */
221 virtual void taggedRelease(const void * tag) const APPLE_KEXT_OVERRIDE;
222
223
224 /*!
225 * @function withString
226 *
227 * @abstract
228 * Returns an OSSymbol created from an OSString,
229 * or the existing unique instance of the same value.
230 *
231 * @param aString The OSString object to look up or copy.
232 *
233 * @result
234 * An instance of OSSymbol
235 * representing the same characters as <code>aString</code>;
236 * <code>NULL</code> on failure.
237 *
238 * @discussion
239 * This function creates or returns the unique OSSymbol instance
240 * representing the string value of <code>aString</code>.
241 * You can compare it with other OSSymbols using the <code>==</code> operator.
242 *
243 * OSSymbols are reference-counted normally.
244 * This function either returns a
245 * new OSSymbol with a retain count of 1,
246 * or increments the retain count of the existing instance.
247 */
248 static const OSSymbol * withString(const OSString * aString);
249
250
251 /*!
252 * @function withCString
253 *
254 * @abstract
255 * Returns an OSSymbol created from a C string,
256 * or the existing unique instance of the same value.
257 *
258 * @param cString The C string to look up or copy.
259 *
260 * @result
261 * An instance of OSSymbol representing
262 * the same characters as <code>cString</code>;
263 * <code>NULL</code> on failure.
264 *
265 * @discussion
266 * This function returns the unique OSSymbol instance
267 * representing the string value of <code>cString</code>.
268 * You can compare it with other OSSymbols using the <code>==</code> operator.
269 *
270 * OSSymbols are reference-counted normally.
271 * This function either returns a
272 * new OSSymbol with a retain count of 1,
273 * or increments the retain count of the existing instance.
274 */
275 static const OSSymbol * withCString(const char * cString);
276
277
278 /*!
279 * @function withCStringNoCopy
280 *
281 * @abstract
282 * Returns an OSSymbol created from a C string,
283 * without copying that string,
284 * or the existing unique instance of the same value.
285 *
286 * @param cString The C string to look up or use.
287 * @result
288 * An instance of OSSymbol representing
289 * the same characters as <code>cString</code>;
290 * <code>NULL</code>.
291 *
292 * @discussion
293 * Avoid using this function;
294 * OSSymbols should own their internal string buffers.
295 *
296 * This function returns the unique OSSymbol instance
297 * representing the string value of <code>cString</code>.
298 * You can compare it with other OSSymbols using the <code>==</code> operator.
299 *
300 * OSSymbols are reference-counted normally.
301 * This function either returns a
302 * new OSSymbol with a retain count of 1,
303 * or increments the retain count of the existing instance.
304 */
305 static const OSSymbol * withCStringNoCopy(const char * cString);
306
307
308 /*!
309 * @function isEqualTo
310 *
311 * @abstract
312 * Tests the equality of two OSSymbol objects.
313 *
314 * @param aSymbol The OSSymbol object being compared against the receiver.
315 *
316 * @result
317 * <code>true</code> if the two OSSymbol objects are equivalent,
318 * <code>false</code> otherwise.
319 *
320 * @discussion
321 * Two OSSymbol objects are considered equal if they have the same address;
322 * that is, this function is equivalent to the <code>==</code> operator.
323 */
324 virtual bool isEqualTo(const OSSymbol * aSymbol) const;
325
326
327 /*!
328 * @function isEqualTo
329 *
330 * @abstract Tests the equality of an OSSymbol object with a C string.
331 *
332 * @param cString The C string to compare against the receiver.
333 *
334 * @result
335 * <code>true</code> if the OSSymbol's characters
336 * are equivalent to the C string's,
337 * <code>false</code> otherwise.
338 */
339 virtual bool isEqualTo(const char * cString) const APPLE_KEXT_OVERRIDE;
340
341
342 /*!
343 * @function isEqualTo
344 *
345 * @abstract Tests the equality of an OSSymbol object to an arbitrary object.
346 *
347 * @param anObject The object to be compared against the receiver.
348 * @result Returns <code>true</code> if the two objects are equivalent,
349 * <code>false</code> otherwise.
350 *
351 * @discussion
352 * An OSSymbol is considered equal to another object
353 * if that object is derived from
354 * @link //apple_ref/doc/class/OSMetaClassBase OSString@/link
355 * and contains the equivalent bytes of the same length.
356 */
357 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
358
359
360#ifdef XNU_KERNEL_PRIVATE
361 /* OSRuntime only INTERNAL API - DO NOT USE */
362 /* Not to be included in headerdoc. */
363 // xx-review: this should be removed from the symbol set.
364
365 static void checkForPageUnload(
366 void * startAddr,
367 void * endAddr);
368
369 static unsigned int bsearch(
370 const void * key,
371 const void * array,
372 unsigned int arrayCount,
373 size_t memberSize);
374#endif /* XNU_KERNEL_PRIVATE */
375
376 OSMetaClassDeclareReservedUnused(OSSymbol, 0);
377 OSMetaClassDeclareReservedUnused(OSSymbol, 1);
378 OSMetaClassDeclareReservedUnused(OSSymbol, 2);
379 OSMetaClassDeclareReservedUnused(OSSymbol, 3);
380 OSMetaClassDeclareReservedUnused(OSSymbol, 4);
381 OSMetaClassDeclareReservedUnused(OSSymbol, 5);
382 OSMetaClassDeclareReservedUnused(OSSymbol, 6);
383 OSMetaClassDeclareReservedUnused(OSSymbol, 7);
384};
385
386#endif /* !_OS_OSSYMBOL_H */
387