Up
Authors
- Richard Frith-Macdonald (
rfm@gnu.org)
-
Date: Generated at 2025-02-11 22:19:38 +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 clean-up
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 clean-up when
the process ends:
1. Use the
+keep:at:
method to register static/global variables whose
contents are to be retained for the lifetime of
the program (up to exit) and either ignored or released
depending on the clean-up setting in force when
the program exits.
This mechanism is simple and
should be sufficient for many classes.
2. Implement an
+atExit
method to be run when the process ends and, within
your
+initialize
implementation,
+registerAtExit
to have your
+atExit
method called when the process exits. Within the
+atExit
method you may call
+shouldCleanUp
to determine whether celan up has been requested.
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 using this API.
+ (BOOL)
isExiting;
Availability: Not in OpenStep/MacOS-X
Returns YES if the process is exiting
(and perhaps performing clean-up).
+ (id)
keep: (id)anObject
at: (id*)anAddress;
Availability: Not in OpenStep/MacOS-X
This method stores anObject at
anAddress (which should be a static or
global variable) and retains it. The code notes that
the object should persist until the process exits. If
clean-up is enabled the object will be released
(and the address content zeroed out) upon process
exit. If this method is called while the process is
already exiting it simply zeros out the memory
location then returns nil, otherwise
it returns the object stored at the memory location.
Raises an exception if anObject is
nil or anAddress is NULL or
the old value at anAddresss is not nil
(unless the process is already exiting).
+ (id)
leak: (id)anObject;
Availability: Not in OpenStep/MacOS-X
+ (id)
leakAt: (id*)anAddress;
Availability: Not in OpenStep/MacOS-X
+ (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
+atExit
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
or if it is already registered to call a method at
exit).
+ (void)
setShouldCleanUp: (BOOL)aFlag;
Availability: Not in OpenStep/MacOS-X
Specifies the default clean-up 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 clean-up 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.
+ (void)
trackOwnership;
Availability: Not in OpenStep/MacOS-X
Turns on tracking of the ownership for all instances
of the receiver. This could have major performance
impact and if possible you should not call this
class method but should use the instance method
instead.
- (void)
trackOwnership;
Availability: Not in OpenStep/MacOS-X
Turns on tracking of ownership for the receiver.
This works best in conjunction with leak
detection (eg as provided by
AddressSanitizer/LeakSanitizer)
which reports leaked memory at program exit: once you
know where leaked memory was allocated, you can alter
the code to call
-trackOwnership
on the offending object, and can then see a log of the
object life cycle to work out why it is leaked.
This operates by altering the class of the
receiver by overriding the
-retain
, -release
, and
-dealloc
methods to report when they are called for the
instance. The logs include the instance address
and the stack trace at which the method was called.
This method also turns on atexit handing to
report tracked instances which have not been
deallocated by the time the process exits. All
instances of a tracked class (and its subclasses)
incur an overhead when the overridden methods are
executed, and that overhead scales with the
number of tracked instances (and classes) so
tracking should be used sparingly (probably never
in production code).
- 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