libkern/libkern/c++/OSSymbol.h

   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     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
 153 protected:
 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
 198 public:
 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 */