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    struct ExpansionData { };
89
90    /* Reserved for future use. (Internal use only)  */
91    ExpansionData * reserved;
92
93    static void initialize();
94
95    // xx-review: not in xnu, delete?
96    friend void checkModuleForSymbols(void); /* in catalogue? */
97
98    // xx-review: these should be removed from the symbol set.
99
100   /*!
101    * @function initWithString
102    *
103    * @abstract
104    * Overridden to prevent creation of duplicate symbols.
105    *
106    * @param aString   Unused.
107    *
108    * @result
109    * <code>false</code>.
110    *
111    * @discussion
112    * Overrides OSString's implementation to prevent creation
113    * of distinct OSSymbols with the same string value.
114    */
115    virtual bool initWithString(const OSString * aString);
116
117
118   /*!
119    * @function initWithCString
120    *
121    * @abstract
122    * Overridden to prevent creation of duplicate symbols.
123    *
124    * @param cString   Unused.
125    *
126    * @result
127    * <code>false</code>.
128    *
129    * @discussion
130    * Overrides OSString's implementation to prevent creation
131    * of distinct OSSymbols with the same string value.
132    */
133    virtual bool initWithCString(const char * cString);
134
135
136   /*!
137    * @function initWithCStringNoCopy
138    *
139    * @abstract
140    * Overridden to prevent creation of duplicate symbols.
141    *
142    * @param cString   Unused.
143    *
144    * @result
145    * <code>false</code>.
146    *
147    * @discussion
148    * Overrides OSString's implementation to prevent creation
149    * of distinct OSSymbols with the same string value.
150    */
151    virtual bool initWithCStringNoCopy(const char *cString);
152
153protected:
154
155// xx-review: should we just omit this from headerdoc?
156   /*!
157    * @function taggedRelease
158    *
159    * @abstract
160    * Overrides
161    * <code>@link
162    * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
163    * OSObject::taggedRelease(const void *, const int)@/link</code>
164    * to synchronize with the symbol pool.
165    *
166    * @param tag      Used for tracking collection references.
167    * @param freeWhen If decrementing the reference count makes it
168    *                 >= <code>freeWhen</code>, the object is immediately freed.
169    *
170    * @discussion
171    * Because OSSymbol shares instances, the reference-counting functions
172    * must synchronize access to the class-internal tables
173    * used to track those instances.
174    */
175    virtual void taggedRelease(
176        const void * tag,
177        const int    freeWhen) const;
178
179
180// xx-review: should we just omit this from headerdoc?
181   /*!
182    * @function free
183    *
184    * @abstract
185    * Overrides
186    * <code>@link
187    * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
188    * OSObject::free@/link</code>
189    * to synchronize with the symbol pool.
190    *
191    * @discussion
192    * Because OSSymbol shares instances, the reference-counting functions
193    * must synchronize access to the class-internal tables
194    * used to track those instances.
195    */
196    virtual void free();
197
198public:
199
200// xx-review: should we just omit this from headerdoc?
201   /*!
202    * @function taggedRelease
203    *
204    * @abstract
205    * Overrides
206    * <code>@link
207    * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
208    * OSObject::taggedRelease(const void *)@/link</code>
209    * to synchronize with the symbol pool.
210    *
211    * @param tag      Used for tracking collection references.
212    *
213    * @discussion
214    * Because OSSymbol shares instances, the reference-counting functions
215    * must synchronize access to the class-internal tables
216    * used to track those instances.
217    */
218
219   /* Original note (not for headerdoc):
220    * The C++ language has forced me to override this method
221    * even though I have implemented it as
222    * <code>{ super::taggedRelease(tag) }</code>.
223    * It seems that C++ is confused about the appearance of the protected
224    * taggedRelease with 2 parameters and refuses to only inherit one function.
225    * See
226    * <code>@link
227    * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
228    * OSObject::taggedRelease(const void *, const int)@/link</code>.
229    */
230    virtual void taggedRelease(const void * tag) const;
231
232
233   /*!
234    * @function withString
235    *
236    * @abstract
237    * Returns an OSSymbol created from an OSString,
238    * or the existing unique instance of the same value.
239    *
240    * @param aString   The OSString object to look up or copy.
241    *
242    * @result
243    * An instance of OSSymbol
244    * representing the same characters  as <code>aString</code>;
245    * <code>NULL</code> on failure.
246    *
247    * @discussion
248    * This function creates or returns the unique OSSymbol instance
249    * representing the string value of <code>aString</code>.
250    * You can compare it with other OSSymbols using the <code>==</code> operator.
251    *
252    * OSSymbols are reference-counted normally.
253    * This function either returns a
254    * new OSSymbol with a retain count of 1,
255    * or increments the retain count of the existing instance.
256    */
257    static const OSSymbol * withString(const OSString * aString);
258
259
260   /*!
261    * @function withCString
262    *
263    * @abstract
264    * Returns an OSSymbol created from a C string,
265    * or the existing unique instance of the same value.
266    *
267    * @param cString   The C string to look up or copy.
268    *
269    * @result
270    * An instance of OSSymbol representing
271    * the same characters as <code>cString</code>;
272    * <code>NULL</code> on failure.
273    *
274    * @discussion
275    * This function returns the unique OSSymbol instance
276    * representing the string value of <code>cString</code>.
277    * You can compare it with other OSSymbols using the <code>==</code> operator.
278    *
279    * OSSymbols are reference-counted normally.
280    * This function either returns a
281    * new OSSymbol with a retain count of 1,
282    * or increments the retain count of the existing instance.
283    */
284    static const OSSymbol * withCString(const char * cString);
285
286
287   /*!
288    * @function withCStringNoCopy
289    *
290    * @abstract
291    * Returns an OSSymbol created from a C string,
292    * without copying that string,
293    * or the existing unique instance of the same value.
294    *
295    * @param cString   The C string to look up or use.
296    * @result
297    * An instance of OSSymbol representing
298    * the same characters as <code>cString</code>;
299    * <code>NULL</code>.
300    *
301    * @discussion
302    * Avoid using this function;
303    * OSSymbols should own their internal string buffers.
304    *
305    * This function returns the unique OSSymbol instance
306    * representing the string value of <code>cString</code>.
307    * You can compare it with other OSSymbols using the <code>==</code> operator.
308    *
309    * OSSymbols are reference-counted normally.
310    * This function either returns a
311    * new OSSymbol with a retain count of 1,
312    * or increments the retain count of the existing instance.
313    */
314    static const OSSymbol * withCStringNoCopy(const char * cString);
315
316
317   /*!
318    * @function isEqualTo
319    *
320    * @abstract
321    * Tests the equality of two OSSymbol objects.
322    *
323    * @param aSymbol The OSSymbol object being compared against the receiver.
324    *
325    * @result
326    * <code>true</code> if the two OSSymbol objects are equivalent,
327    * <code>false</code> otherwise.
328    *
329    * @discussion
330    * Two OSSymbol objects are considered equal if they have the same address;
331    * that is, this function is equivalent to the <code>==</code> operator.
332    */
333    virtual bool isEqualTo(const OSSymbol * aSymbol) const;
334
335
336   /*!
337    * @function isEqualTo
338    *
339    * @abstract Tests the equality of an OSSymbol object with a C string.
340    *
341    * @param cString  The C string to compare against the receiver.
342    *
343    * @result
344    * <code>true</code> if the OSSymbol's characters
345    * are equivalent to the C string's,
346    * <code>false</code> otherwise.
347    */
348    virtual bool isEqualTo(const char * cString) const;
349
350
351   /*!
352    * @function isEqualTo
353    *
354    * @abstract Tests the equality of an OSSymbol object to an arbitrary object.
355    *
356    * @param anObject The object to be compared against the receiver.
357    * @result         Returns <code>true</code> if the two objects are equivalent,
358    *                 <code>false</code> otherwise.
359    *
360    * @discussion
361    * An OSSymbol is considered equal to another object
362    * if that object is derived from
363    * @link //apple_ref/doc/class/OSMetaClassBase OSString@/link
364    * and contains the equivalent bytes of the same length.
365    */
366    virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
367
368
369#ifdef XNU_KERNEL_PRIVATE
370   /* OSRuntime only INTERNAL API - DO NOT USE */
371   /* Not to be included in headerdoc. */
372    // xx-review: this should be removed from the symbol set.
373
374    static void checkForPageUnload(
375        void * startAddr,
376        void * endAddr);
377
378    static unsigned int bsearch(
379	const void *  key,
380	const void *  array,
381	unsigned int  arrayCount,
382	size_t        memberSize);
383#endif /* XNU_KERNEL_PRIVATE */
384
385    OSMetaClassDeclareReservedUnused(OSSymbol, 0);
386    OSMetaClassDeclareReservedUnused(OSSymbol, 1);
387    OSMetaClassDeclareReservedUnused(OSSymbol, 2);
388    OSMetaClassDeclareReservedUnused(OSSymbol, 3);
389    OSMetaClassDeclareReservedUnused(OSSymbol, 4);
390    OSMetaClassDeclareReservedUnused(OSSymbol, 5);
391    OSMetaClassDeclareReservedUnused(OSSymbol, 6);
392    OSMetaClassDeclareReservedUnused(OSSymbol, 7);
393};
394
395#endif /* !_OS_OSSYMBOL_H */
396