Up

NSObject+GNUstepBase documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Copyright: (C) 2003-2010 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSObject(GNUstepBase) informal protocol
  2. Software documentation for the NSObject(GSAtExit) informal protocol
  3. Software documentation for the NSObject(GSCleanup) informal protocol

Software documentation for the NSObject(GNUstepBase) informal protocol

NSObject(GNUstepBase)

Declared in:
GNUstepBase/NSObject+GNUstepBase.h
Availability: Not in OpenStep/MacOS-X

Description forthcoming.
Method summary

compare: 

- (NSComparisonResult) compare: (id)anObject;
Availability: Not in OpenStep/MacOS-X

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 

- (BOOL) isInstance;
Availability: Not in OpenStep/MacOS-X

For backward compatibility only... use class_isMetaClass() on the class of the receiver instead.

makeImmutableCopyOnFail: 

- (id) makeImmutableCopyOnFail: (BOOL)force;
Availability: Not in OpenStep/MacOS-X

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: 

- (id) notImplemented: (SEL)aSel;
Availability: Not in OpenStep/MacOS-X

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: 

- (id) shouldNotImplement: (SEL)aSel;
Availability: Not in OpenStep/MacOS-X

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: 

- (id) subclassResponsibility: (SEL)aSel;
Availability: Not in OpenStep/MacOS-X

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

NSObject(GSAtExit)

Declared in:
GNUstepBase/NSObject+GNUstepBase.h
Availability: Not in OpenStep/MacOS-X

This is an informal protocol... classes may implement the method and register themselves to have it called on process exit.
Method summary

atExit 

+ (void) atExit;
Availability: Not in OpenStep/MacOS-X

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

NSObject(GSCleanup)

Declared in:
GNUstepBase/NSObject+GNUstepBase.h
Availability: Not in OpenStep/MacOS-X

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.

Method summary

leak: 

+ (id) leak: (id)anObject;
Availability: Not in OpenStep/MacOS-X

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: 

+ (id) leakAt: (id*)anAddress;
Availability: Not in OpenStep/MacOS-X

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 

+ (BOOL) registerAtExit;
Availability: Not in OpenStep/MacOS-X

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: 

+ (BOOL) registerAtExit: (SEL)aSelector;
Availability: Not in OpenStep/MacOS-X

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: 

+ (void) setShouldCleanUp: (BOOL)aFlag;
Availability: Not in OpenStep/MacOS-X

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 

+ (BOOL) shouldCleanUp;
Availability: Not in OpenStep/MacOS-X

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.


Up