# NSObject+GNUstepBase documentation

rfm@gnu.org
2003-2010 Free Software Foundation, Inc.
Software documentation for the NSObject(GNUstepBase) informal protocol
GNUstepBase/NSObject+GNUstepBase.h
Description forthcoming.
compare:
anObject
WARNING: The -compare: method for NSObject is deprecated due to subclasses declaring the same selector with conflicting signatures. Comparision of arbitrary objects is not just meaningless but also dangerous as most concrete implementations expect comparable objects as arguments often accessing instance variables directly. This method will be removed in a future release.
isInstance
For backward compatibility only... use class_isMetaClass() on the class of the receiver instead.
makeImmutableCopyOnFail:
force
Transmutes the receiver into an immutable version of the same object and returns the result.
If the receiver is not a mutable object or cannot be simply transmuted, then this method either returns the receiver unchanged or, if the force flag is set to `YES`, returns an autoreleased copy of the receiver.
Mutable classes should override this default implementation.
This method is used in methods which are declared to return immutable objects (eg. an NSArray), but which create and build mutable ones internally.
notImplemented:
aSel
Message sent when an implementation wants to explicitly exclude a method (but cannot due to compiler constraint), and wants to make sure it is not called by mistake. Default implementation raises an exception at runtime.
shouldNotImplement:
aSel
Message sent when an implementation wants to explicitly exclude a method (but cannot due to compiler constraint) and forbid that subclasses implement it. Default implementation raises an exception at runtime. If a subclass does implement this method, however, the superclass's implementation will not be called, so this is not a perfect mechanism.
subclassResponsibility:
aSel
Message sent when an implementation wants to explicitly require a subclass to implement a method (but cannot at compile time since there is no `abstract` keyword in Objective-C). Default implementation raises an exception at runtime to alert developer that he/she forgot to override a method.
Software documentation for the NSObject(GSAtExit) informal protocol
GNUstepBase/NSObject+GNUstepBase.h
This is an informal protocol... classes may implement the method and register themselves to have it called on process exit.
atExit
This method is called on exit for any class which implements it and which has called +registerAtExit to register it to be called.
The order in which methods for different classes is called is the reverse of the order in which the classes were registered, but it's best to assume the method can not depend on any other class being in a usable state at the point when the method is called (rather like +load).
Typical use would be to release memory occupied by class data structures so that memory usage analysis software will not think the memory has been leaked.
Software documentation for the NSObject(GSCleanup) informal protocol
GNUstepBase/NSObject+GNUstepBase.h
Category for methods handling leaked memory cleanup on exit of process (for use when debugging memory leaks).
You enable this by calling the +setShouldCleanUp: method (done implicitly by gnustep-base if the GNUSTEP_SHOULD_CLEAN_UP environment variable is set to `YES`).
Your class then has two options for performing cleanup when the process ends:

1. Use the +leak: method to register objects which are simply to be retained until the process ends, and then either ignored or released depending on the cleanup setting in force. This mechanism is simple and should be sufficient for many classes.

2. Implement a +atExit method to be run when the process ends and, within your +initialize implementation, call +shouldCleanUp to determine whether cleanup should be done, and if it returns `YES` then call +registerAtExit to have your +atExit method called when the process terminates.

The order in which 'leaked' objects are released and +atExit methods are called on process exist is the reverse of the order in which they werse set up suing this API.

leak:
anObject
This method simply retains its argument so that it will never be deallocated during normal operation, but keeps track of it so that it is released during process exit if cleanup is enabled.
Returns its argument.
leakAt:
anAddress
This method retains the object at *anAddress so that it will never be deallocated during normal operation, but keeps track of the address so that the object is released and the address is zeroed during process exit if cleanup is enabled.
Returns the object at *anAddress.
registerAtExit
Sets the receiver to have its +atExit method called at the point when the process terminates.
Returns `YES` on success and `NO` on failure (if the class does not implement the method or if it is already registered to call it).
Implemented as a call to +registerAtExit: with the selector for the +atExit method as its argument.
registerAtExit:
aSelector
Sets the receiver to have the specified method called at the point when the process terminates.
Returns `YES` on success and `NO` on failure (if the class does not implement the method ir if it is already registered to call it).
setShouldCleanUp:
aFlag
Specifies the default cleanup behavior on process exit... the value returned by the NSObject implementation of the +shouldClanUp method.
Calling this method with a `YES` argument implicitly calls the +enableAtExit method as well.
The GNUstep Base library calls this method with the value obtained from the GNUSTEP_SHOULD_CLEAN_UP environment variable when NSObject is initialised.
shouldCleanUp
Returns a flag indicating whether the receiver should clean up its data structures etc at process exit.
The NSObject implementation returns the value set by the +setShouldCleanUp: method but subclasses may override this.