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
  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 */