NSObject

Authors

Richard Frith-Macdonald

Nicola Pero

Version: $Revision$

Date: $Date$

NSObject

NSObject

Declared in: Foundation/NSObject.h

Conforms to: NSObject

NSObject is the root class (a root class is a class with no superclass) of the gnustep base library class hierarchy, so all classes normally inherit from NSObject. There is an exception though: NSProxy (which is used for remote messaging) does not inherit from NSObject.

Unless you are really sure of what you are doing, all your own classes should inherit (directly or indirectly) from NSObject (or in special cases from NSProxy). NSObject provides the basic common functionality shared by all gnustep classes and objects.

The essential methods which must be implemented by all classes for their instances to be usable within gnustep are declared in a separate protocol, which is the NSObject protocol. Both NSObject and NSProxy conform to this protocol, which means all objects in a gnustep application will conform to this protocol (btw, if you don't find a method of NSObject you are looking for in this documentation, make sure you also look into the documentation for the NSObject protocol).

Theoretically, in special cases you might need to implement a new root class. If you do, you need to make sure that your root class conforms (at least) to the NSObject protocol, otherwise it will not interact correctly with the gnustep framework. Said that, I must note that I have never seen a case in which a new root class is needed.

NSObject is a root class, which implies that instance methods of NSObject are treated in a special way by the Objective-C runtime. This is an exception to the normal way messaging works with class and instance methods: if the Objective-C runtime can't find a class method for a class object, as a last resort it looks for an instance method of the root class with the same name, and executes it if it finds it. This means that instance methods of the root class (such as NSObject) can be performed by class objects which inherit from that root class ! This can only happen if the class doesn't have a class method with the same name, otherwise that method - of course - takes the precedence. Because of this exception, NSObject's instance methods are written in such a way that they work both on NSObject's instances and on class objects.

Instance Variables

Methods

• +alloc
• +allocWithZone:
• +cancelPreviousPerformRequestsWithTarget:selector:
• +class
• +conformsToProtocol:
• +copyWithZone:
• +description
• +descriptionWithLocale:
• +descriptionWithLocale:indent:
• +descriptionWithLocale:indent:to:
• +initialize
• +instanceMethodForSelector:
• +instanceMethodSignatureForSelector:
• +instancesRespondToSelector:
• +load
• +mutableCopyWithZone:
• +new
• +poseAsClass:
• +setVersion:
• +superclass
• +version
• -_dealloc
• -awakeAfterUsingCoder:
• -classForArchiver
• -classForCoder
• -classForPortCoder
• -connection:handleRequest:
• -copy
• -dealloc
• -deallocNotificationsActive
• -description
• -descriptionWithLocale:
• -descriptionWithLocale:indent:
• -descriptionWithLocale:indent:to:
• -doesNotRecognizeSelector:
• -forwardInvocation:
• -hash
• -init
• -isEqual:
• -methodForSelector:
• -methodSignatureForSelector:
• -mutableCopy
• -performSelector:withObject:
• -performSelector:withObject:afterDelay:inModes:
• -replacementObjectForArchiver:
• -replacementObjectForCoder:
• -replacementObjectForPortCoder:
• -setDeallocNotificationsActive:

Class Methods

alloc

allocWithZone:

Memory for an instance of the receiver is allocated; a pointer to this newly created instance is returned. All instance variables are set to 0 except the isa pointer which is set to point to the object class. No initialization of the instance is performed: it is your responsibility to initialize the instance by calling an appropriate init method. If you are not using the garbage collector, it is also your responsibility to make sure the returned instance is destroyed when you finish using it, by calling the release method to destroy the instance directly, or by using autorelease and autorelease pools.

You do not normally need to override this method in subclasses, unless you are implementing a class which for some reasons silently allocates instances of another class (this is typically needed to implement class clusters and similar design schemes).

If you have turned on debugging of object allocation (by calling the GSDebugAllocationActive function), this method will also update the various debugging counts and monitors of allocated objects, which you can access using the GSDebugAllocation... functions.

cancelPreviousPerformRequestsWithTarget:selector:

class

conformsToProtocol:

copyWithZone:

description

descriptionWithLocale:

descriptionWithLocale:indent:

descriptionWithLocale:indent:to:

initialize

instanceMethodForSelector:

instanceMethodSignatureForSelector:

instancesRespondToSelector:

load

mutableCopyWithZone:

new

NSObject *object = [NSObject new];

NSObject *object = [[NSObject alloc] init];

This is a general convention: all new... methods are supposed to return a newly allocated and initialized instance, as would be generated by an alloc method followed by a corresponding init... method. Please note that if you are not using a garbage collector, this means that instances generated by the new... methods are not autoreleased, that is, you are responsible for releasing (autoreleasing) the instances yourself. So when you use new you typically do something like:

NSMutableArray *array = AUTORELEASE ([NSMutableArray new]);

You do no normally need to override new in subclasses, because if you override init (and optionally allocWithZone: if you really need), new will automatically use your subclass methods.

You might need instead to define new new... methods specific to your subclass to match any init... specific to your subclass. For example, if your subclass defines

-initWithName:

it might be handy for you to have a

+newWithName:

which combines alloc and initWithName:. You would implement it as follows:

+ (id) newWithName: (NSString *)aName { return [[self alloc] initWithName: aName]; }

poseAsClass:

setVersion:

superclass

version

Instances Methods

awakeAfterUsingCoder:

classForArchiver

classForCoder

classForPortCoder

connection:handleRequest:

copy

dealloc

NSObject's implementation of this method destroys the receiver, by returning the memory allocated to the receiver to the system. After this method has been called on an instance, you must not refer the instance in any way, because it does not exist any longer. If you do, it is a bug and your program might even crash with a segmentation fault.

If you have turned on the debugging facilities for instance allocation, NSObject's implementation of this method will also update the various counts and monitors of allocated instances (see the GSDebugAllocation... functions for more info).

Normally you are supposed to manage the memory taken by objects by using the high level interface provided by the retain, release and autorelease methods (or better by the corresponding macros RETAIN, RELEASE and AUTORELEASE), and by autorelease pools and such; whenever the release/autorelease mechanism determines that an object is no longer needed (which happens when its retain count reaches 0), it will call the dealloc method to actually deallocate the object. This means that normally, you should not need to call dealloc directly as the gnustep base library automatically calls it for you when the retain count of an object reaches 0.

Because the dealloc method will be called when an instance is being destroyed, if instances of your subclass use objects or resources (as it happens for most useful classes), you must override dealloc in subclasses to release all objects and resources which are used by the instance, otherwise these objects and resources would be leaked. In the subclass implementation, you should first release all your subclass specific objects and resources, and then invoke super's implementation (which will do the same, and so on up in the class hierarchy to NSObject's implementation, which finally destroys the object). Here is an example of the implementation of dealloc for a subclass whose instances have a single instance variable name which needs to be released when an instance is deallocated:

- (void) dealloc { RELEASE (name); [super dealloc]; }

dealloc might contain code to release not only objects, but also other resources, such as open files, network connections, raw memory allocated in other ways, etc.

description

The description method describes the reciever. In the default GNUstep implementation, this returns an NSString object giving the name of the class of the receiver and the hexadecimal representation of the recievers address enclosed in angle brackets.

Generally, classes other than NSObject will override this method to provide a more informative description of their instances.

descriptionWithLocale:

descriptionWithLocale:indent:

descriptionWithLocale:indent:to:

Property-list classes (NSString, NSArray, NSDictionary and NSData) will override this method in order to efficiently write descriptions of themselves into property lists.

doesNotRecognizeSelector:

forwardInvocation:

hash

init

isEqual:

methodForSelector:

methodSignatureForSelector:

mutableCopy

performSelector:withObject:

performSelector:withObject:afterDelay:inModes:

replacementObjectForArchiver:

replacementObjectForCoder:

replacementObjectForPortCoder:

deallocNotificationsActive

Returns a boolean indicating whether deallocation notification has been turned on.

If deallocation notification is turned on, whenever an objects retain count reaches zero (and it would normally be deallocated) the _dealloc methiod is called and the object is only deallocated if that method returns YES.

setDeallocNotificationsActive:

Turns on (or off) deallocation notification.

If deallocation notification is turned on, whenever an objects retain count reaches zero (and it would normally be deallocated) the _dealloc methiod is called and the object is only deallocated if that method returns YES.

_dealloc

Returns a boolean indicating whether the receiver should be deallocated or not. The default implementation returns YES.

This method is called when an objects retain count reaches zero (if deallocation notifications are active).

This method is provided so that you can take some sort of action when objects are deallocated ... normally you would override this method in your classes, but you could also override it in a category of NSObject - and perform some action whenever any object is deallocated.