Up
Authors
- Richard Frith-Macdonald (
rfm@gnu.org)
-
Date: Generated at 2024-11-18 21:56:54 +0100
Copyright: (C) 2003-2010 Free Software Foundation, Inc.
- Declared in:
- GNUstepBase/NSObject+GNUstepBase.h
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
- (
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.
- (BOOL)
isInstance;
Availability: Not in OpenStep/MacOS-X
For backward compatibility only... use
"class_isMetaClass()" on the class of
the receiver instead.
- (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.
- (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.
- (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.
- (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.
- (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.
- 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.
+ (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.
- 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.
+ (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.
+ (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.
+ (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.
+ (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).
+ (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
+shouldCleanUp
method.
Calling this method with a
YES argument implicitly enables the
support for cleanup at exit.
The GNUstep
Base library calls this method with the value obtained
from the GNUSTEP_SHOULD_CLEAN_UP environment variable
when NSObject is initialised.
+ (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.
- Declared in:
- GNUstepBase/NSObject+GNUstepBase.h
Availability: Not in OpenStep/MacOS-X
This is an informal protocol; classes may implement the
+contentSizeOf: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.
+ (
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
- (
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.
- (
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.
- (
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 instance variables.
- (
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