Mac Developer Library

Developer

Foundation Framework Reference NSGarbageCollector Class Reference

Options
Deployment Target:

On This Page
Language:

NSGarbageCollector

Inheritance


Conforms To


Import Statement


Not Applicable

Objective-C

@import Foundation;

Availability


Available in OS X v10.5 and later.
Deprecated in OS X v10.10.

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

  • Returns the default garbage collector.

    Declaration

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • disable - disable (OS X v10.10)

    Temporarily disables collections.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

    See Also

    – enable

  • enable - enable (OS X v10.10)

    Enables collection after collection has been disabled.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • isEnabled - isEnabled (OS X v10.10)

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

    Declaration

    Objective-C

    - (BOOL)isEnabled

    Return Value

    YEStrue if garbage collection is enabled for the current process, otherwise NOfalse.

    Discussion

    This method returns NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • Returns a Boolean value that indicates whether a collection is currently in progress.

    Declaration

    Objective-C

    - (BOOL)isCollecting

    Return Value

    YEStrue if a collection is currently in progress, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Tells the receiver to collect iteratively.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • Specifies that a given pointer will not be collected.

    Declaration

    Objective-C

    - (void)disableCollectorForPointer:(const 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • Specifies that a given pointer may be collected.

    Declaration

    Objective-C

    - (void)enableCollectorForPointer:(const 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.

  • zone - zone (OS X v10.10)

    Returns a zone of unscanned memory.

    Declaration

    Objective-C

    - (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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.10.