1 /** Declaration of extension methods for base additions 2 3 Copyright (C) 2003-2010 Free Software Foundation, Inc. 4 5 Written by: Richard Frith-Macdonald <rfm@gnu.org> 6 and: Adam Fedor <fedor@gnu.org> 7 8 This file is part of the GNUstep Base Library. 9 10 This library is free software; you can redistribute it and/or 11 modify it under the terms of the GNU Lesser General Public 12 License as published by the Free Software Foundation; either 13 version 2 of the License, or (at your option) any later version. 14 15 This library is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 Library General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with this library; if not, write to the Free 22 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 23 Boston, MA 02111 USA. 24 25 */ 26 27 #ifndef INCLUDED_NSObject_GNUstepBase_h 28 #define INCLUDED_NSObject_GNUstepBase_h 29 30 #import "GSVersionMacros.h" 31 #import "../Foundation/NSObject.h" 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 #if OS_API_VERSION(GS_API_NONE,GS_API_LATEST) 38 39 @class NSHashTable; 40 41 @interface NSObject (GNUstepBase) 42 43 /** 44 WARNING: The -compare: method for NSObject is deprecated 45 due to subclasses declaring the same selector with 46 conflicting signatures. 47 Comparision of arbitrary objects is not just meaningless 48 but also dangerous as most concrete implementations 49 expect comparable objects as arguments often accessing 50 instance variables directly. 51 This method will be removed in a future release. 52 */ 53 - (NSComparisonResult) compare: (id)anObject; 54 55 /** For backward compatibility only ... use class_isMetaClass() on the 56 * class of the receiver instead. 57 */ 58 - (BOOL) isInstance; 59 60 /** DEPRECATED ... do not use. 61 * Transmutes the receiver into an immutable version of the same object 62 * and returns the result.<br /> 63 * If the receiver is not a mutable object or cannot be simply transmuted, 64 * then this method either returns the receiver unchanged or, 65 * if the force flag is set to YES, returns an autoreleased copy of the 66 * receiver.<br /> 67 * Mutable classes should override this default implementation.<br /> 68 * This method is used in methods which are declared to return immutable 69 * objects (eg. an NSArray), but which create and build mutable ones 70 * internally. 71 */ 72 - (id) makeImmutableCopyOnFail: (BOOL)force; 73 74 /** Transmutes the receiver into an immutable version of the same object. 75 * Returns YES if the receiver has become immutable, NO otherwise.<br /> 76 * The default implementation returns NO.<br /> 77 * Mutable classes which have an immutable counterpart they can efficiently 78 * change into, should override to transmute themselves and return YES.<br /> 79 * Immutable classes should override this to simply return YES with no 80 * further action.<br /> 81 * This method is used in methods which are declared to return immutable 82 * objects (eg. an NSArray), but which create and build mutable ones 83 * internally. 84 */ 85 - (BOOL) makeImmutable; 86 87 /** 88 * Message sent when an implementation wants to explicitly exclude a method 89 * (but cannot due to compiler constraint), and wants to make sure it is not 90 * called by mistake. Default implementation raises an exception at runtime. 91 */ 92 - (id) notImplemented: (SEL)aSel GS_NORETURN_METHOD; 93 94 /** 95 * Message sent when an implementation wants to explicitly require a subclass 96 * to implement a method (but cannot at compile time since there is no 97 * <code>abstract</code> keyword in Objective-C). Default implementation 98 * raises an exception at runtime to alert developer that he/she forgot to 99 * override a method. 100 */ 101 - (id) subclassResponsibility: (SEL)aSel GS_NORETURN_METHOD; 102 103 /** 104 * Message sent when an implementation wants to explicitly exclude a method 105 * (but cannot due to compiler constraint) and forbid that subclasses 106 * implement it. Default implementation raises an exception at runtime. If a 107 * subclass <em>does</em> implement this method, however, the superclass's 108 * implementation will not be called, so this is not a perfect mechanism. 109 */ 110 - (id) shouldNotImplement: (SEL)aSel GS_NORETURN_METHOD; 111 112 @end 113 114 /** This is an informal protocol ... classes may implement the method to 115 * report how much memory is used by the instance and any objects it acts 116 * as a container for. 117 */ 118 @interface NSObject(MemoryFootprint) 119 /* This method returns the memory usage of the receiver, excluding any 120 * objects already present in the exclude table.<br /> 121 * The argument is a hash table configured to hold non-retained pointer 122 * objects and is used to inform the receiver that its size should not 123 * be counted again if it's already in the table.<br /> 124 * The NSObject implementation returns zero if the receiver is in the 125 * table, but otherwise adds itself to the table and returns its memory 126 * footprint (the sum of all of its instance variables, but not any 127 * memory pointed to by those variables).<br /> 128 * Subclasses should override this method by calling the superclass 129 * implementation, and either return the result (if it was zero) or 130 * return that value plus the sizes of any memory owned by the receiver 131 * (eg found by calling the same method on objects pointed to by the 132 * receiver's instance variables). 133 */ 134 - (NSUInteger) sizeInBytesExcluding: (NSHashTable*)exclude; 135 @end 136 137 /** This is an informal protocol ... classes may implement the method and 138 * register themselves to have it called on process exit. 139 */ 140 @interface NSObject(GSAtExit) 141 /** This method is called on exit for any class which implements it and which 142 * has called +registerAtExit to register it to be called.<br /> 143 * The order in which methods for different classes is called is the reverse 144 * of the order in which the classes were registered, but it's best to assume 145 * the method can not depend on any other class being in a usable state 146 * at the point when the method is called (rather like +load).<br /> 147 * Typical use would be to release memory occupied by class data structures 148 * so that memory usage analysis software will not think the memory has 149 * been leaked. 150 */ 151 + (void) atExit; 152 @end 153 154 /** Category for methods handling leaked memory cleanup on exit of process 155 * (for use when debugging memory leaks).<br /> 156 * You enable this by calling the +setShouldCleanUp: method (done implicitly 157 * by gnustep-base if the GNUSTEP_SHOULD_CLEAN_UP environment variable is 158 * set to YES).<br /> 159 * Your class then has two options for performing cleanup when the process 160 * ends: 161 * <p>1. Use the +leak: method to register objects which are simply to be 162 * retained until the process ends, and then either ignored or released 163 * depending on the cleanup setting in force. This mechanism is simple 164 * and should be sufficient for many classes. 165 * </p> 166 * <p>2. Implement a +atExit method to be run when the process ends and, 167 * within your +initialize implementation, call +shouldCleanUp to determine 168 * whether cleanup should be done, and if it returns YES then call 169 * +registerAtExit to have your +atExit method called when the process 170 * terminates. 171 * </p> 172 * <p>The order in which 'leaked' objects are released and +atExit methods 173 * are called on process exist is the reverse of the order in which they 174 * werse set up suing this API. 175 * </p> 176 */ 177 @interface NSObject(GSCleanup) 178 179 180 /** This method simply retains its argument so that it will never be 181 * deallocated during normal operation, but keeps track of it so that 182 * it is released during process exit if cleanup is enabled.<br /> 183 * Returns its argument. 184 */ 185 + (id) NS_RETURNS_RETAINED leak: (id)anObject; 186 187 /** This method retains the object at *anAddress so that it will never be 188 * deallocated during normal operation, but keeps track of the address 189 * so that the object is released and the address is zeroed during process 190 * exit if cleanup is enabled.<br /> 191 * Returns the object at *anAddress. 192 */ 193 + (id) NS_RETURNS_RETAINED leakAt: (id*)anAddress; 194 195 /** Sets the receiver to have its +atExit method called at the point when 196 * the process terminates.<br /> 197 * Returns YES on success and NO on failure (if the class does not implement 198 * the method or if it is already registered to call it).<br /> 199 * Implemented as a call to +registerAtExit: with the selector for the +atExit 200 * method as its argument. 201 */ 202 + (BOOL) registerAtExit; 203 204 /** Sets the receiver to have the specified method called at the point when 205 * the process terminates.<br /> 206 * Returns YES on success and NO on failure (if the class does not implement 207 * the method ir if it is already registered to call it). 208 */ 209 + (BOOL) registerAtExit: (SEL)aSelector; 210 211 /** Specifies the default cleanup behavior on process exit ... the value 212 * returned by the NSObject implementation of the +shouldClanUp method.<br /> 213 * Calling this method with a YES argument implicitly calls the +enableAtExit 214 * method as well.<br /> 215 * The GNUstep Base library calls this method with the value obtained from 216 * the GNUSTEP_SHOULD_CLEAN_UP environment variable when NSObject is 217 * initialised. 218 */ 219 + (void) setShouldCleanUp: (BOOL)aFlag; 220 221 /** Returns a flag indicating whether the receiver should clean up 222 * its data structures etc at process exit.<br /> 223 * The NSObject implementation returns the value set by the +setShouldCleanUp: 224 * method but subclasses may override this. 225 */ 226 + (BOOL) shouldCleanUp; 227 228 @end 229 230 /* Macro to take an autoreleased object and either make it immutable or 231 * create an autoreleased copy of the original. 232 */ 233 #define GS_IMMUTABLE(O) ([O makeImmutable] == YES ? O : AUTORELEASE([O copy])) 234 235 #endif /* OS_API_VERSION */ 236 237 #if defined(__cplusplus) 238 } 239 #endif 240 241 #endif /* INCLUDED_NSObject_GNUstepBase_h */ 242 243