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