1 /**Interface for NSObject for GNUStep
2 Copyright (C) 1995, 1996, 1998 Free Software Foundation, Inc.
3
4 Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
5 Date: 1995
6
7 This file is part of the GNUstep Base Library.
8
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Lesser General Public
11 License as published by the Free Software Foundation; either
12 version 2 of the License, or (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library; if not, write to the Free
21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02111 USA.
23
24 AutogsdocSource: NSObject.m
25 */
26
27 #ifndef __NSObject_h_GNUSTEP_BASE_INCLUDE
28 #define __NSObject_h_GNUSTEP_BASE_INCLUDE
29
30 #import "NSObjCRuntime.h"
31 #import <objc/objc.h>
32 #import "NSZone.h"
33
34 #ifdef GS_WITH_GC
35 #undef GS_WITH_GC
36 #endif
37 #define GS_WITH_GC 0
38
39 #import "../GNUstepBase/GNUstep.h"
40
41 #if defined(__cplusplus)
42 extern "C" {
43 #endif
44
45 @class NSArchiver;
46 @class NSArray;
47 @class NSCoder;
48 @class NSDictionary;
49 @class NSPortCoder;
50 @class NSMethodSignature;
51 @class NSMutableString;
52 @class NSRecursiveLock;
53 @class NSString;
54 @class NSInvocation;
55 @class Protocol;
56
57 /**
58 * The NSObject protocol describes a minimal set of methods that all
59 * objects are expected to support. You should be able to send any
60 * of the messages listed in this protocol to an object, and be safe
61 * in assuming that the receiver can handle it.
62 */
63 @protocol NSObject
64 /**
65 * Returns the class of the receiver. If the receiver is a proxy, then this
66 * may return the class of the proxy target. Use -isProxy to determine whether
67 * the receiver is a proxy. If you wish to find the real class of the
68 * receiver, ignoring proxies, then use object_getClass().
69 */
70 - (Class) class;
71 /**
72 * Returns the superclass of receiver's class. If the receiver is a proxy,
73 * then this may return the class of the proxy target. Use -isProxy to
74 * determine whether the receiver is a proxy. If you wish to find the real
75 * superclass of the receiver's class, ignoring proxies, then use
76 * class_getSuperclass(object_getClass()).
77 */
78 - (Class) superclass;
79 /**
80 * Returns whether the receiver is equal to the argument. Defining equality is
81 * complex, so be careful when implementing this method. Collections such as
82 * NSSet depend on the behaviour of this method. In particular, this method
83 * must be commutative, so for any objects a and b:
84 *
85 * [a isEqual: b] == [b isEqual: a]
86 *
87 * This means that you must be very careful when returning YES if the argument
88 * is of another class. For example, if you define a number class that returns
89 * YES if the argument is a string representation of the number, then this will
90 * break because the string will not recognise your object as being equal to
91 * itself.
92 *
93 * If two objects are equal, then they must have the same hash value, however
94 * equal hash values do not imply equality.
95 */
96 - (BOOL) isEqual: (id)anObject;
97 /**
98 * Returns YES if the receiver is an instance of the class, an instance of the
99 * subclass, or (in the case of proxies), an instance of something that can be
100 * treated as an instance of the class.
101 */
102 - (BOOL) isKindOfClass: (Class)aClass;
103 /**
104 * Returns YES if the receiver is an instance of the class or (in the case of
105 * proxies), an instance of something that can be treated as an instance of the
106 * class.
107 *
108 * Calling this method is rarely the correct thing to do. In most cases, a
109 * subclass can be substituted for a superclass, so you should never need to
110 * check that an object is really an instance of a specific class and not a
111 * subclass.
112 */
113 - (BOOL) isMemberOfClass: (Class)aClass;
114 /**
115 * Returns YES if the receiver is a proxy, NO otherwise. The default
116 * implementation of this method in NSObject returns NO, while the
117 * implementation in NSProxy returns YES.
118 */
119 - (BOOL) isProxy;
120 /**
121 * Returns a hash value for the object. All objects that are equal *MUST*
122 * return the same hash value. For efficient storage in sets, or as keys in
123 * dictionaries, different objects should return hashes spread evenly over the
124 * range of an integer.
125 *
126 * An object may not return different values from this method after being
127 * stored in a collection. This typically means that ether the hash value must
128 * be constant after the object's creation, or that the object may not be
129 * modified while stored in an unordered collection.
130 */
131 - (NSUInteger) hash;
132 /**
133 * Returns the receiver. In a proxy, this may (but is not required to) return
134 * the proxied object.
135 */
136 - (id) self;
137 /**
138 * Performs the specified selector. The selector must correspond to a method
139 * that takes no arguments.
140 */
141 - (id) performSelector: (SEL)aSelector;
142 /**
143 * Performs the specified selector, with the object as the argument. This
144 * method does not perform any automatic unboxing, so the selector must
145 * correspond to a method that takes one object argument.
146 */
147 - (id) performSelector: (SEL)aSelector
148 withObject: (id)anObject;
149 /**
150 * Performs the specified selector, with the objects as the arguments. This
151 * method does not perform any automatic unboxing, so the selector must
152 * correspond to a method that takes two object arguments.
153 */
154 - (id) performSelector: (SEL)aSelector
155 withObject: (id)object1
156 withObject: (id)object2;
157 /**
158 * Returns YES if the object can respond to messages with the specified
159 * selector. The default implementation in NSObject returns YES if the
160 * receiver has a method corresponding to the method, but other classes may
161 * return YES if they can respond to a selector using one of the various
162 * forwarding mechanisms.
163 */
164 - (BOOL) respondsToSelector: (SEL)aSelector;
165 /**
166 * Returns YES if the receiver conforms to the specified protocol.
167 */
168 - (BOOL) conformsToProtocol: (Protocol*)aProtocol;
169 /**
170 * Increments the reference count of the object and returns the receiver. In
171 * garbage collected mode, this method does nothing. In automated reference
172 * counting mode, you may neither implement this method nor call it directly.
173 */
174 - (id) retain NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
175 /**
176 * Decrements the reference count of the object and destroys if it there are no
177 * remaining references. In garbage collected mode, this method does nothing.
178 * In automated reference counting mode, you may neither implement this method
179 * nor call it directly.
180 */
181 - (oneway void) release NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
182 /**
183 * Performs a deferred -release operation. The object's reference count is
184 * decremented at the end of the scope of the current autorelease pool,
185 * identified either by a -drain message sent to the current NSAutoreleasePool
186 * instance, or in more recent versions of Objective-C by the end of an
187 * @autorelease_pool scope.
188 *
189 * In garbage collected mode, this method does nothing. In automated reference
190 * counting mode, you may neither implement this method nor call it directly.
191 */
192 - (id) autorelease NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
193 /**
194 * Returns the current retain count of an object. This does not include the
195 * result of any pending autorelease operations.
196 *
197 * Code that relies on this method returning a sane value is broken. For
198 * singletons, it may return NSUIntegerMax. Even when it is tracking a retain
199 * count, it will not include on-stack pointers in manual retain/release mode,
200 * pointers marked as __unsafe_unretain or __weak in ARC mode, or pending
201 * autorelease operations. Its value is therefore largely meaningless. It can
202 * occasionally be useful for debugging.
203 */
204 - (NSUInteger) retainCount NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
205 /**
206 * Returns the description of the object. This is used by the %@ format
207 * specifier in strings.
208 */
209 - (NSString*) description;
210 /**
211 * Returns the zone of the object.
212 */
213 - (NSZone*) zone NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
214 @end
215
216 /**
217 * This protocol must be adopted by any class wishing to support copying -
218 * ie where instances of the class should be able to create new instances
219 * which are copies of the original and, where a class has mutable and
220 * immutable versions, where the copies are immutable.
221 */
222 @protocol NSCopying
223 /**
224 * Called by [NSObject-copy] passing NSDefaultMallocZone() as zone.<br />
225 * This method returns a copy of the receiver and, where the receiver is a
226 * mutable variant of a class which has an immutable partner class, the
227 * object returned is an instance of that immutable class.<br />
228 * The new object is <em>not</em> autoreleased, and is considered to be
229 * 'owned' by the calling code ... which is therefore responsible for
230 * releasing it.<br />
231 * In the case where the receiver is an instance of a container class,
232 * it is undefined whether contained objects are merely retained in the
233 * new copy, or are themselves copied, or whether some other mechanism
234 * entirely is used.
235 */
236 - (id) copyWithZone: (NSZone*)zone;
237 @end
238
239 /**
240 * This protocol must be adopted by any class wishing to support
241 * mutable copying - ie where instances of the class should be able
242 * to create mutable copies of themselves.
243 */
244 @protocol NSMutableCopying
245 /**
246 * Called by [NSObject-mutableCopy] passing NSDefaultMallocZone() as zone.<br />
247 * This method returns a copy of the receiver and, where the receiver is an
248 * immutable variant of a class which has a mutable partner class, the
249 * object returned is an instance of that mutable class.
250 * The new object is <em>not</em> autoreleased, and is considered to be
251 * 'owned' by the calling code ... which is therefore responsible for
252 * releasing it.<br />
253 * In the case where the receiver is an instance of a container class,
254 * it is undefined whether contained objects are merely retained in the
255 * new copy, or are themselves copied, or whether some other mechanism
256 * entirely is used.
257 */
258 - (id) mutableCopyWithZone: (NSZone*)zone;
259 @end
260
261 /**
262 * This protocol must be adopted by any class wishing to support
263 * saving and restoring instances to an archive, or copying them
264 * to remote processes via the Distributed Objects mechanism.
265 */
266 @protocol NSCoding
267
268 /**
269 * Called when it is time for receiver to be serialized for writing to an
270 * archive or network connection. Receiver should record all of its instance
271 * variables using methods on aCoder. See documentation for [NSCoder],
272 * [NSArchiver], [NSKeyedArchiver], and/or [NSPortCoder] for more information.
273 */
274 - (void) encodeWithCoder: (NSCoder*)aCoder;
275
276 /**
277 * Called on a freshly allocated receiver when it is time to reconstitute from
278 * serialized bytes in an archive or from a network connection. Receiver
279 * should load all of its instance variables using methods on aCoder. See
280 * documentation for [NSCoder], [NSUnarchiver], [NSKeyedUnarchiver], and/or
281 * [NSPortCoder] for more information.
282 */
283 - (id) initWithCoder: (NSCoder*)aDecoder;
284 @end
285
286 @protocol NSSecureCoding <NSCoding>
287 + (BOOL)supportsSecureCoding;
288 @end
289
290
291 GS_ROOT_CLASS @interface NSObject <NSObject>
292 {
293 /**
294 * Points to instance's class. Used by runtime to access method
295 * implementations, etc.. Set in +alloc, Unlike other instance variables,
296 * which are cleared there.
297 */
298 Class isa;
299 }
300
301 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
302 /** On a system which performs garbage collection, you should implement
303 * this method to execute code when the receiver is collected.<br />
304 * You must not call this method yourself (except when a subclass
305 * calls the superclass method within its own implementation).
306 */
307 - (void) finalize;
308 #endif
309
310 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
311 - (NSString*) className;
312 #endif
313
314 + (id) allocWithZone: (NSZone*)z;
315 + (id) alloc;
316 + (Class) class;
317
318 /**
319 * This method is automatically invoked on any class which implements it
320 * when the class is loaded into the runtime.<br />
321 * It is also invoked on any category where the method is implemented
322 * when that category is loaded into the runtime.<br />
323 * The +load method is called directly by the runtime and you should never
324 * send a +load message to a class yourself.<br />
325 * This method is called <em>before</em> the +initialize message is sent
326 * to the class, so you cannot depend on class initialisation having been
327 * performed, or upon other classes existing (apart from superclasses of
328 * the receiver, since +load is called on superclasses before it is called
329 * on their subclasses).<br />
330 * As a gross generalisation, it is safe to use C code, including
331 * most ObjectiveC runtime functions within +load, but attempting to send
332 * messages to ObjectiveC objects is likely to fail.<br />
333 * In GNUstep, this method is implemented for NSObject to perform some
334 * initialisation for the base library.<br />
335 * If you implement +load for a class, don't call [super load] in your
336 * implementation.
337 */
338 + (void) load;
339
340 /**
341 * This message is automatically sent to a class by the runtime. It is
342 * sent once for each class, just before the class is used for the first
343 * time (excluding any automatic call to +load by the runtime).<br />
344 * The message is sent in a thread-safe manner ... other threads may not
345 * call methods of the class until +initialize has finished executing.<br />
346 * If the class has a superclass, its implementation of +initialize is
347 * called first.<br />
348 * If the class does not implement +initialize then the implementation
349 * in the closest superclass may be called. This means that +initialize may
350 * be called more than once, and the recommended way to handle this by
351 * using the
352 * <code>
353 * if (self == [classname class])
354 * </code>
355 * conditional to check whether the method is being called for a subclass.<br />
356 * You should never call +initialize yourself ... let the runtime do it.<br />
357 * You can implement +initialize in your own class if you need to.
358 * NSObject's implementation handles essential root object and base
359 * library initialization.<br />
360 * It should be safe to call [super initialize] in your implementation
361 * of +initialize.
362 */
363 + (void) initialize;
364 + (IMP) instanceMethodForSelector: (SEL)aSelector;
365 + (NSMethodSignature*) instanceMethodSignatureForSelector: (SEL)aSelector;
366 + (BOOL) instancesRespondToSelector: (SEL)aSelector;
367 + (BOOL) isSubclassOfClass: (Class)aClass;
368 + (id) new;
369 + (void) poseAsClass: (Class)aClassObject;
370 + (id) setVersion: (NSInteger)aVersion;
371 + (NSInteger) version;
372
373 - (id) awakeAfterUsingCoder: (NSCoder*)aDecoder;
374 - (Class) classForArchiver;
375 - (Class) classForCoder;
376 - (id) copy;
377 - (void) dealloc;
378 - (void) doesNotRecognizeSelector: (SEL)aSelector;
379 - (void) forwardInvocation: (NSInvocation*)anInvocation;
380 - (id) init;
381 - (IMP) methodForSelector: (SEL)aSelector;
382 - (NSMethodSignature*) methodSignatureForSelector: (SEL)aSelector;
383 - (id) mutableCopy;
384 - (id) replacementObjectForArchiver: (NSArchiver*)anArchiver;
385 - (id) replacementObjectForCoder: (NSCoder*)anEncoder;
386 - (Class) superclass;
387 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
388 /**
389 * This method will be called when attempting to send a message a class that
390 * does not understand it. The class may install a new method for the given
391 * selector and return YES, otherwise it should return NO.
392 *
393 * Note: This method is only reliable when using the GNUstep runtime. If you
394 * require compatibility with the GCC runtime, you must also implement
395 * -forwardInvocation: with equivalent semantics. This will be considerably
396 * slower, but more portable.
397 */
398 + (BOOL) resolveClassMethod: (SEL)name;
399
400 /**
401 * This method will be called when attempting to send a message an instance
402 * that does not understand it. The class may install a new method for the
403 * given selector and return YES, otherwise it should return NO.
404 *
405 * Note: This method is only reliable when using the GNUstep runtime. If you
406 * require compatibility with the GCC runtime, you must also implement
407 * -forwardInvocation: with equivalent semantics. This will be considerably
408 * slower, but more portable.
409 */
410 + (BOOL) resolveInstanceMethod: (SEL)name;
411 #endif
412 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST)
413 /**
414 * Returns an auto-accessing proxy for the given object. This proxy sends a
415 * -beginContentAccess message to the receiver when it is created and an
416 * -endContentAccess message when it is destroyed. This prevents an object
417 * that implements the NSDiscardableContent protocol from having its contents
418 * discarded for as long as the proxy exists.
419 *
420 * On systems using the GNUstep runtime, messages send to the proxy will be
421 * slightly slower than direct messages. With the GCC runtime, they will be
422 * approximately two orders of magnitude slower. The GNUstep runtime,
423 * therefore, is strongly recommended for code calling this method.
424 */
425 - (id) autoContentAccessingProxy;
426
427 /**
428 * If an object does not understand a message, it may delegate it to another
429 * object. Returning nil indicates that forwarding should not take place. The
430 * default implementation of this returns nil, but care should be taken when
431 * subclassing NSObject subclasses and overriding this method that
432 * the superclass implementation is called if returning nil.
433 *
434 * Note: This method is only reliable when using the GNUstep runtime and code
435 * compiled with clang. If you require compatibility with GCC and the GCC
436 * runtime, you must also implement -forwardInvocation: with equivalent
437 * semantics. This will be considerably slower, but more portable.
438 */
439 - (id) forwardingTargetForSelector: (SEL)aSelector;
440
441 #endif
442 @end
443
444 /**
445 * Used to allocate memory to hold an object, and initialise the
446 * class of the object to be aClass etc. The allocated memory will
447 * be extraBytes larger than the space actually needed to hold the
448 * instance variables of the object.<br />
449 * This function is used by the [NSObject+allocWithZone:] method.
450 */
451 GS_EXPORT id
452 NSAllocateObject(Class aClass, NSUInteger extraBytes, NSZone *zone);
453
454 /**
455 * Used to release the memory used by an object.<br />
456 * This function is used by the [NSObject-dealloc] method.
457 */
458 GS_EXPORT void
459 NSDeallocateObject(id anObject);
460
461 /**
462 * Used to copy anObject. This makes a bitwise copy of anObject to
463 * memory allocated from zone. The allocated memory will be extraBytes
464 * longer than that necessary to actually store the instance variables
465 * of the copied object.<br />
466 */
467 GS_EXPORT NSObject *
468 NSCopyObject(NSObject *anObject, NSUInteger extraBytes, NSZone *zone);
469
470 /**
471 * Returns a flag to indicate whether anObject should be retained or
472 * copied in order to make a copy in the specified zone.<br />
473 * Basically, this tests to see if anObject was allocated from
474 * requestedZone and returns YES if it was.
475 */
476 GS_EXPORT BOOL
477 NSShouldRetainWithZone(NSObject *anObject, NSZone *requestedZone);
478
479 GS_EXPORT BOOL
480 NSDecrementExtraRefCountWasZero(id anObject);
481
482 GS_EXPORT NSUInteger
483 NSExtraRefCount(id anObject);
484
485 GS_EXPORT void
486 NSIncrementExtraRefCount(id anObject);
487
488 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE)
489
490 /** Global lock to be used by classes when operating on any global
491 data that invoke other methods which also access global; thus,
492 creating the potential for deadlock. */
493 GS_EXPORT NSRecursiveLock *gnustep_global_lock;
494
495 @interface NSObject (NEXTSTEP)
496 - (id) error:(const char *)aString, ...;
497 /* - (const char *) name;
498 Removed because OpenStep has -(NSString*)name; */
499 @end
500
501 #if GS_API_VERSION(GS_API_NONE, 011700)
502 @interface NSObject (GNUstep)
503 + (void) enableDoubleReleaseCheck: (BOOL)enable;
504 @end
505 #endif
506
507 #endif
508
509 #import "NSDate.h"
510 /**
511 * Declares some methods for sending messages to self after a fixed delay.
512 * (These methods <em>are</em> in OpenStep and OS X.)
513 */
514 @interface NSObject (TimedPerformers)
515
516 /**
517 * Cancels any perform operations set up for the specified target
518 * in the current run loop.
519 */
520 + (void) cancelPreviousPerformRequestsWithTarget: (id)obj;
521
522 /**
523 * Cancels any perform operations set up for the specified target
524 * in the current loop, but only if the value of aSelector and argument
525 * with which the performs were set up match those supplied.<br />
526 * Matching of the argument may be either by pointer equality or by
527 * use of the [NSObject-isEqual:] method.
528 */
529 + (void) cancelPreviousPerformRequestsWithTarget: (id)obj
530 selector: (SEL)s
531 object: (id)arg;
532 /**
533 * Sets given message to be sent to this instance after given delay,
534 * in any run loop mode. See [NSRunLoop].
535 */
536 - (void) performSelector: (SEL)s
537 withObject: (id)arg
538 afterDelay: (NSTimeInterval)seconds;
539
540 /**
541 * Sets given message to be sent to this instance after given delay,
542 * in given run loop modes. See [NSRunLoop].
543 */
544 - (void) performSelector: (SEL)s
545 withObject: (id)arg
546 afterDelay: (NSTimeInterval)seconds
547 inModes: (NSArray*)modes;
548 @end
549
550 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST)
551 /**
552 * The NSDiscardableContent protocol is used by objects which encapsulate data
553 * which may be discarded if resource constraints are exceeded. These
554 * constraints are typically, but not always, related memory.
555 */
556 @protocol NSDiscardableContent
557
558 /**
559 * This method is called before any access to the object. It returns YES if
560 * the object's content is still valid. The caller must call -endContentAccess
561 * once for every call to -beginContentAccess;
562 */
563 - (BOOL) beginContentAccess;
564
565 /**
566 * Discards the contents of the object if it is not currently being edited.
567 */
568 - (void) discardContentIfPossible;
569
570 /**
571 * This method indicates that the caller has finished accessing the contents of
572 * the object adopting this protocol. Every call to -beginContentAccess must
573 * be be paired with a call to this method after the caller has finished
574 * accessing the contents.
575 */
576 - (void) endContentAccess;
577
578 /**
579 * Returns YES if the contents of the object have been discarded, either via a
580 * call to -discardContentIfPossible while the object is not in use, or by some
581 * implementation dependent mechanism.
582 */
583 - (BOOL) isContentDiscarded;
584 @end
585 #endif
586 #if defined(__cplusplus)
587 }
588 #endif
589
590 #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL)
591 #import "../GNUstepBase/NSObject+GNUstepBase.h"
592 #endif
593
594 #endif /* __NSObject_h_GNUSTEP_BASE_INCLUDE */