libkern/libkern/c++/OSSymbol.h

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