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