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
4. Software documentation for the NSObject(MemoryFootprint) 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:
- -isInstance
- -makeImmutable
- -makeImmutableCopyOnFail:
- -notImplemented:
- -shouldNotImplement:
- -subclassResponsibility:

### 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.

### makeImmutable

- (BOOL) makeImmutable;
Availability: Not in OpenStep/MacOS-X
Transmutes the receiver into an immutable version of the same object. Returns `YES` if the receiver has become immutable, `NO` otherwise.
The default implementation returns `NO`.
Mutable classes which have an immutable counterpart they can efficiently change into, should override to transmute themselves and return `YES`.
Immutable classes should override this to simply return `YES` with no further action.
This method is used in methods which are declared to return immutable objects (eg. an NSArray), but which create and build mutable ones internally.

### makeImmutableCopyOnFail:

- (id) makeImmutableCopyOnFail: (BOOL)force;
Availability: Not in OpenStep/MacOS-X
DEPRECATED... do not use. 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

### 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:
- +leakAt:
- +registerAtExit
- +registerAtExit:
- +setShouldCleanUp:
- +shouldCleanUp

### 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.

# Software documentation for the NSObject(MemoryFootprint) informal protocol

## NSObject(MemoryFootprint)

> Declared in:
>   GNUstepBase/NSObject+GNUstepBase.h

Availability: Not in OpenStep/MacOS-X
This is an informal protocol; classes may implement the +contentSizeOf:declaredIn:excluding: method to report how much memory is used by any objects/pointers it acts as a container for.
Code may call the -sizeInBytesExcluding: or -sizeinBytes method to determine how much heap memory an object (and its content) occupies.
Method summary

- +contentSizeOf:excluding:
- -sizeInBytes
- -sizeInBytesExcluding:
- -sizeOfContentExcluding:
- -sizeOfInstance

### contentSizeOf: excluding:

+ (NSUInteger) contentSizeOf: (NSObject*)obj excluding: (NSHashTable*)exclude;
Availability: Not in OpenStep/MacOS-X
This method returns the size of the memory used by the object instance variables of the target object (excluding any in the specified set).
This is not the memory occupied by instance variable pointers. It is the memory referenced by any objects inside the target.
This method is not intended to be overridden, rather it is provided for use as a helper for the -sizeOfContentExcluding: method.
This method must not be called for a mutable object unless it is protected by a locking mechanism to prevent mutation while it is examining the instance variables of the object.

     @interface	foo : bar
     {
       id	a;		// Some object
       id b;		// More storage
       unsigned capacity;	// Buffer size
       char *p;		// The buffer
     }
     @end
     @implementation foo
     - (NSUInteger) sizeOfContentExcluding: (NSHashTable*)exclude
    {
      NSUInteger	size;

      // get the size of the objects (a and b)
      size = [NSObject contentSizeOf: self
    			 excluding: exclude];
      // add the memory pointed to by p
      size += capacity * sizeof(char);
      return size;
    }
    @end

### sizeInBytes

- (NSUInteger) sizeInBytes;
Availability: Not in OpenStep/MacOS-X
Convenience method calling -sizeInBytesExcluding: with a newly created exclusion hash table, and destroying the table once the size is calculated.

### sizeInBytesExcluding:

- (NSUInteger) sizeInBytesExcluding: (NSHashTable*)exclude;
Availability: Not in OpenStep/MacOS-X
This method returns the memory usage of the receiver, excluding any objects already present in the exclude table.
The argument is a hash table configured to hold non-retained pointer objects and is used to inform the receiver that its size should not be counted again if it's already in the table.
The NSObject implementation returns zero if the receiver is in the table, but otherwise adds itself to the table and returns its memory footprint (the sum of all of its instance variables, plus the result of calling -sizeOfContentExcluding: for the instance).
Classes should not override this method, instead they should implement -sizeOfContentExcluding: to return the extra memory usage of the pointer/object instance variables (heap memory) they add to their superclass.
NB. mutable objects must either prevent mutation while calculating their content size, or must override -sizeOfContentExcluding: to refrain from dealing with content which might change.

### sizeOfContentExcluding:

- (NSUInteger) sizeOfContentExcluding: (NSHashTable*)exclude;
Availability: Not in OpenStep/MacOS-X
This method is called by -sizeInBytesExcluding: to calculate the size of any objects or heap memory contained by the receiver.
The base class implementation simply returns zero (as it is not possible to safely calculate content sizes of mutable objects), but subclasses should override it to provide correct information where possible (eg if the object is immutable or if locking is used to prevent mutation while calculating content size).
Subclasses may use the +contentSizeOf:excluding: method as a convenience to provide the sizes of object instnce variables.

### sizeOfInstance

- (NSUInteger) sizeOfInstance;
Availability: Not in OpenStep/MacOS-X
Helper method called by -sizeInBytesExcluding: to return the size of the instance excluding any contents (things referenced by pointers).

Up