Mac Developer Library

Developer

Foundation Framework Reference NSDiscardableContent Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSDiscardableContent

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.6 and later.

You implement this protocol when a class’s objects have subcomponents that can be discarded when not being used, thereby giving an application a smaller memory footprint.

An NSDiscardableContent object’s life cycle is dependent upon a “counter” variable. An NSDiscardableContent object is a purgeable block of memory that keeps track of whether or not it is currently being used by some other object. When this memory is being read, or is still needed, its counter variable will be greater than or equal to 1. When it is not being used, and can be discarded, the counter variable will be equal to 0.

When the counter is equal to 0, the block of memory may be discarded if memory is tight at that point in time. In order to discard the content, call discardContentIfPossible on the object, which will free the associated memory if the counter variable equals 0.

By default, NSDiscardableContent objects are initialized with their counter equal to 1 to ensure that they are not immediately discarded by the memory-management system. From this point, you must keep track of the counter variable’s state. Calling the beginContentAccess method increments the counter variable by 1, thus ensuring that the object will not be discarded. When you no longer need the object, decrement its counter by calling endContentAccess.

The Foundation framework includes the NSPurgeableData class, which provides a default implementation of this protocol.

  • Returns a Boolean value indicating whether the discardable contents are still available and have been successfully accessed. (required)

    Declaration

    Swift

    func beginContentAccess() -> Bool

    Objective-C

    - (BOOL)beginContentAccess

    Return Value

    YES if the discardable contents are still available and have now been successfully accessed; otherwise, NOfalse.

    Discussion

    Call this method if the object’s memory is needed or is about to be used. This method increments the counter variable, thus protecting the object’s memory from possibly being discarded. The implementing class may decide that this method will try to recreate the contents if they have been discarded and return YES if the re-creation was successful. Implementors of this protocol should raise exceptions if the NSDiscardableContent objects are used when the beginContentAccess method has not been called on them.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Called if the discardable contents are no longer being accessed. (required)

    Declaration

    Swift

    func endContentAccess()

    Objective-C

    - (void)endContentAccess

    Discussion

    This method decrements the counter variable of the object, which will usually bring the value of the counter variable back down to 0, which allows the discardable contents of the object to be thrown away if necessary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Called to discard the contents of the receiver if the value of the accessed counter is 0. (required)

    Declaration

    Swift

    func discardContentIfPossible()

    Objective-C

    - (void)discardContentIfPossible

    Discussion

    This method should only discard the contents of the object if the value of the accessed counter is 0. Otherwise, it should do nothing.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Returns a Boolean value indicating whether the content has been discarded. (required)

    Declaration

    Swift

    func isContentDiscarded() -> Bool

    Objective-C

    - (BOOL)isContentDiscarded

    Return Value

    YEStrue if the content has been discarded; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.