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 | */ |
81 | class OSSymbol : public OSString |
82 | { |
83 | friend class OSSymbolPool; |
84 | |
85 | OSDeclareAbstractStructors(OSSymbol) |
86 | |
87 | private: |
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 | |
144 | protected: |
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 | |
189 | public: |
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 | |