NSGarbageCollector Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.5 and later.
Companion guide
Garbage Collection Programming Guide
Declared in
NSGarbageCollector.h

Overview

NSGarbageCollector provides a convenient interface to the garbage collection system.

Cocoa’s garbage collector is a conservative generational garbage collector. It uses “write-barriers” to detect cross generational stores of pointers so that “young” objects can be collected quickly.

You enable garbage collection (GC) by using the -fobjc-gc compiler option. This switch causes the generation of the write-barrier assignment primitives. You must use this option on your main application file and all others used by the application, including frameworks and bundles. Bundles are ignored if they are not GC-capable.

The collector determines what is garbage by recursively examining all nodes starting with globals, possible nodes referenced from the thread stacks, and all nodes marked as having “external” references. Nodes not reached by this search are deemed garbage. Weak references to garbage nodes are then cleared.

Garbage nodes that are objects are sent (in an arbitrary order) a finalize message, and after all finalize messages have been sent their memory is recovered. It is a runtime error (referred to as “resurrection”) to store a object being finalized into one that is not. For more details, see “Implementing a finalize Method” in Garbage Collection Programming Guide.

You can request collection from any thread (see collectIfNeeded and collectExhaustively).

Tasks

Shared Instance

Collection State

Triggering Collection

Manipulating External References

Accessing an Unscanned Memory Zone

Class Methods

defaultCollector

Returns the default garbage collector.

+ (id)defaultCollector
Return Value

The default garbage collector for the current process. Returns nil if the current process is not running with garbage collection.

Discussion

There is at most one garbage collector for Cocoa within a single process.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

Instance Methods

collectExhaustively

Tells the receiver to collect iteratively.

- (void)collectExhaustively
Discussion

You use this method to indicate to the collector that it should perform an exhaustive collection. Collection is subject to interruption on user input.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

collectIfNeeded

Tells the receiver to collect if memory consumption thresholds have been exceeded.

- (void)collectIfNeeded
Discussion

You use this method to indicate to the collector that there is an opportunity to perform a collection. Collection is subject to interruption on user input.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

disable

Temporarily disables collections.

- (void)disable
Discussion

Invocations of this method can be nested. To reenable collection, you must send the collector an enable message once for each invocation of this method.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSGarbageCollector.h

disableCollectorForPointer:

Specifies that a given pointer will not be collected.

- (void)disableCollectorForPointer:(void *)ptr
Parameters
ptr

A pointer to the memory that should not be collected.

Discussion

You use this method to ensure that memory at a given address will not be collected. You can use this, for example, to create new root objects:

NSMutableDictionary *globalDictionary;
globalDictionary = [NSMutableDictionary dictionary];
[[NSGarbageCollector defaultCollector]
    disableCollectorForPointer:globalDictionary];

The new dictionary will not be collectable and will persist for the lifetime of the application unless it is subsequently passed as the argument to enableCollectorForPointer:. For more about root objects and scanned memory, see Garbage Collection Programming Guide.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

enable

Enables collection after collection has been disabled.

- (void)enable
Discussion

This method balances a single invocation of disable. To reenable collection, this method must be invoked as many times as was disable.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

enableCollectorForPointer:

Specifies that a given pointer may be collected.

- (void)enableCollectorForPointer:(void *)ptr
Parameters
ptr

A pointer to the memory that may be collected.

Discussion

You use this method to make memory that was previously marked as uncollectable. For example, given the address of the global dictionary created in disableCollectorForPointer:, you could make the dictionary collectable as follows:

[[NSGarbageCollector defaultCollector]
    enableCollectorForPointer:globalDictionary];

For more about root objects and scanned memory, see Garbage Collection Programming Guide.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

isEnabled

Returns a Boolean value that indicates whether garbage collection is currently enabled for the current process.

- (BOOL)isEnabled
Return Value

YES if garbage collection is enabled for the current process, otherwise NO.

Discussion

This method returns NO if garbage collection is on, but has been temporarily suspended (using disable).

To check whether the current process is using garbage collection check the result of [NSGarbageCollector defaultCollector]. If defaultCollector is nil, then garbage collection is permanently off. If defaultCollector is not nil, then the current process is using garbage collection—you can then use isEnabled to determine whether or not the collector is actually allowed to run right now.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h

zone

Returns a zone of unscanned memory.

- (NSZone *)zone
Return Value

A memory zone of memory that is not scanned.

Discussion

The collector provides a NSZoneMalloc-style allocation interface, primarily for compatibility with existing code that maintains zone affinity. Such memory is unscanned and you must free it using NSZoneFree.  This is exactly equivalent to calling NSAllocateCollectable with the option NSCollectorDisabledOption.

You should typically allocate garbage-collected memory using NSAllocateCollectable

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGarbageCollector.h