libkern/libkern/c++/OSSymbol.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /* IOSymbol.h created by gvdl on Fri 1998-10-30 */
  31 /* IOSymbol must be created through the factory methods and thus is not subclassable. */
  32
  33 #ifndef _OS_OSSYMBOL_H
  34 #define _OS_OSSYMBOL_H
  35
  36 #include <libkern/c++/OSString.h>
  37
  38 /*!
  39     @class OSSymbol
  40     @abstract A container class whose instances represent unique string values.
  41     @discussion
  42     An OSSymbol object represents a unique string value.  When creating an OSSymbol, a string is given and an OSSymbol representing this string is created if none exist for this string.  If a symbol for this string already exists, then a reference to an existing symbol is returned.
  43 */
  44 class OSSymbol : public OSString
  45 {
  46     friend class OSSymbolPool;
  47
  48     OSDeclareAbstractStructors(OSSymbol)
  49
  50 private:
  51     struct ExpansionData { };
  52
  53     /*! @var reserved
  54         Reserved for future use.  (Internal use only)  */
  55     ExpansionData *reserved;
  56
  57     static void initialize();
  58
  59     friend void checkModuleForSymbols(void); /* in catalogue? */
  60
  61     // The string init methods have to be removed from the inheritance.
  62     virtual bool initWithString(const OSString *aString);
  63     virtual bool initWithCString(const char *cString);
  64     virtual bool initWithCStringNoCopy(const char *cString);
  65
  66 protected:
  67     /*!
  68         @function taggedRelease
  69         @abstract Overriden super class release method so we can synchronise with the symbol pool.
  70         @discussion When we release an symbol we need to synchronise the destruction of the object with any potential searches that may be occuring through the family factor methods.  See OSObject::taggedRelease
  71     */
  72     virtual void taggedRelease(const void *tag, const int when) const;
  73
  74     /*!
  75         @function free
  76         @abstract Overriden super class release method so we can synchronise with the symbol pool.
  77         @discussion When we release an symbol we need to synchronise the destruction of the object with any potential searches that may be occuring through the family factor methods.  See OSObject::free
  78     */
  79     virtual void free();
  80
  81 public:
  82     /*!
  83         @function taggedRelease
  84         @abstract Release a tag.
  85         @discussion The C++ language has forced me to override this method even though I have implemented it as { super::taggedRelease(tag) }. It seems that C++ is confused about the appearance of the protected taggedRelease with 2 args and refuses to only inherit one function.  See OSObject::taggedRelease
  86     */
  87     virtual void taggedRelease(const void *tag) const;
  88
  89
  90     /*!
  91         @function withString
  92         @abstract A static constructor function to create an OSSymbol instance from an OSString object or returns an existing OSSymbol object based on the OSString object given.
  93         @param aString An OSString object.
  94         @result Returns a unique OSSymbol object for the string given.
  95     */
  96     static const OSSymbol *withString(const OSString *aString);
  97     /*!
  98         @function withCString
  99         @abstract A static constructor function to create an OSSymbol instance from a simple c-string returns an existing OSSymbol object based on the string object given.
 100         @param cString A c-string.
 101         @result Returns a unique OSSymbol object for the string given.
 102     */
 103     static const OSSymbol *withCString(const char *cString);
 104     /*!
 105         @function withCStringNoCopy
 106         @abstract A static constructor function to create an OSSymbol instance from a simple c-string, but does not copy the string to the container.
 107         @param cString A c-string.
 108         @result Returns a unique OSSymbol object for the string given.
 109     */
 110     static const OSSymbol *withCStringNoCopy(const char *cString);
 111
 112     /*!
 113         @function isEqualTo
 114         @abstract A member function which tests the equality between two OSSymbol objects.  Two OSSymbol objects are only equivalent when their references are identical
 115         @param aSymbol The OSSymbol object to be compared against the receiver.
 116         @result Returns true if the two objects are equivalent, false otherwise.
 117     */
 118     virtual bool isEqualTo(const OSSymbol *aSymbol) const;
 119     /*!
 120         @function isEqualTo
 121         @abstract A member function which tests the equality between an OSSymbol object and a simple c-string.
 122         @param aCString The c-string to be compared against the receiver.
 123         @result Returns true if the OSSymbol's internal string representation is equivalent to the c-string it is being compared against, false otherwise.
 124     */
 125     virtual bool isEqualTo(const char *aCString) const;
 126     /*!
 127         @function isEqualTo
 128         @abstract A member function which tests the equality between an OSSymbol object and and arbitrary OSObject derived object.
 129         @param obj The OSObject derived object to be compared against the receiver.
 130         @result Returns true if the OSSymbol and the OSObject objects are equivalent.
 131     */
 132     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 133
 134     /* OSRuntime only INTERNAL API - DO NOT USE */
 135     static void checkForPageUnload(void *startAddr, void *endAddr);
 136
 137
 138     OSMetaClassDeclareReservedUnused(OSSymbol, 0);
 139     OSMetaClassDeclareReservedUnused(OSSymbol, 1);
 140     OSMetaClassDeclareReservedUnused(OSSymbol, 2);
 141     OSMetaClassDeclareReservedUnused(OSSymbol, 3);
 142     OSMetaClassDeclareReservedUnused(OSSymbol, 4);
 143     OSMetaClassDeclareReservedUnused(OSSymbol, 5);
 144     OSMetaClassDeclareReservedUnused(OSSymbol, 6);
 145     OSMetaClassDeclareReservedUnused(OSSymbol, 7);
 146 };
 147
 148 #endif /* !_OS_OSSYMBOL_H */