| 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 <[email protected]> |
| 6 |
and: Adam Fedor <[email protected]> |
| 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 |
|