Mac Developer Library

Developer

Foundation Framework Reference NSCache Class Reference

Options
Deployment Target:

On This Page
Language:

NSCache

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.6 and later.

An NSCache object is a collection-like container, or cache, that stores key-value pairs, similar to the NSDictionary class. Developers often incorporate caches to temporarily store objects with transient data that are expensive to create. Reusing these objects can provide performance benefits, because their values do not have to be recalculated. However, the objects are not critical to the application and can be discarded if memory is tight. If discarded, their values will have to be recomputed again when needed.

While a key-value pair is in the cache, the cache maintains a strong reference to it. A common data type stored in NSCache objects is an object that implements the NSDiscardableContent protocol. Storing this type of object in a cache has benefits, because its content can be discarded when it is not needed anymore, thus saving memory. By default, NSDiscardableContent objects in the cache are automatically removed from the cache if their content is discarded, although this automatic removal policy can be changed. If an NSDiscardableContent object is put into the cache, the cache calls discardContentIfPossible on it upon its removal.

NSCache objects differ from other mutable collections in a few ways:

  • The NSCache class incorporates various auto-removal policies, which ensure that it does not use too much of the system’s memory. The system automatically carries out these policies if memory is needed by other applications. When invoked, these policies remove some items from the cache, minimizing its memory footprint.

  • You can add, remove, and query items in the cache from different threads without having to lock the cache yourself.

  • Unlike an NSMutableDictionary object, a cache does not copy the key objects that are put into it.

These features are necessary for the NSCache class, as the cache may decide to automatically mutate itself asynchronously behind the scenes if it is called to free up memory.

  • name name Property

    The name of the cache.

    Declaration

    Swift

    var name: String

    Objective-C

    @property(copy) NSString *name

    Discussion

    The empty string if no name is specified.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Returns the value associated with a given key.

    Declaration

    Swift

    func objectForKey(_ key: AnyObject) -> AnyObject?

    Objective-C

    - (id)objectForKey:(id)key

    Parameters

    key

    An object identifying the value.

    Return Value

    The value associated with key, or nil if no value is associated with key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Sets the value of the specified key in the cache.

    Declaration

    Swift

    func setObject(_ obj: AnyObject, forKey key: AnyObject)

    Objective-C

    - (void)setObject:(id)obj forKey:(id)key

    Parameters

    obj

    The object to be stored in the cache.

    key

    The key with which to associate the value.

    Discussion

    Unlike an NSMutableDictionary object, a cache does not copy the key objects that are put into it.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Sets the value of the specified key in the cache, and associates the key-value pair with the specified cost.

    Declaration

    Swift

    func setObject(_ obj: AnyObject, forKey key: AnyObject, cost num: Int)

    Objective-C

    - (void)setObject:(id)obj forKey:(id)key cost:(NSUInteger)num

    Parameters

    obj

    The object to store in the cache.

    key

    The key with which to associate the value.

    num

    The cost with which to associate the key-value pair.

    Discussion

    The cost value is used to compute a sum encompassing the costs of all the objects in the cache. When memory is limited or when the total cost of the cache eclipses the maximum allowed total cost, the cache could begin an eviction process to remove some of its elements. However, this eviction process is not in a guaranteed order. As a consequence, if you try to manipulate the cost values to achieve some specific behavior, the consequences could be detrimental to your program. Typically, the obvious cost is the size of the value in bytes. If that information is not readily available, you should not go through the trouble of trying to compute it, as doing so will drive up the cost of using the cache. Pass in 0 for the cost value if you otherwise have nothing useful to pass, or simply use the setObject:forKey: method, which does not require a cost value to be passed in.

    Unlike an NSMutableDictionary object, a cache does not copy the key objects that are put into it.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Removes the value of the specified key in the cache.

    Declaration

    Swift

    func removeObjectForKey(_ key: AnyObject)

    Objective-C

    - (void)removeObjectForKey:(id)key

    Parameters

    key

    The key identifying the value to be removed.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Empties the cache.

    Declaration

    Swift

    func removeAllObjects()

    Objective-C

    - (void)removeAllObjects

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • The maximum number of objects the cache should hold.

    Declaration

    Swift

    var countLimit: Int

    Objective-C

    @property NSUInteger countLimit

    Discussion

    The default value is 0, which means no limit.

    This is not a strict limit—if the cache goes over the limit, an object in the cache could be evicted instantly, later, or possibly never, depending on the implementation details of the cache.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • The maximum total cost that the cache can hold before it starts evicting objects.

    Declaration

    Swift

    var totalCostLimit: Int

    Objective-C

    @property NSUInteger totalCostLimit

    Discussion

    The default value is 0, which indicates no limit.

    When you add an object to the cache, you may pass in a specified cost for the object, such as the size in bytes of the object. If adding this object to the cache causes the cache’s total cost to rise above totalCostLimit, the cache may automatically evict objects until its total cost falls below totalCostLimit. The order in which the cache evicts objects is not guaranteed.

    This is not a strict limit, and if the cache goes over the limit, an object in the cache could be evicted instantly, at a later point in time, or possibly never, all depending on the implementation details of the cache.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Boolean value that indicates whether the cache will automatically evict discardable-content objects whose content has been discarded.

    Declaration

    Swift

    var evictsObjectsWithDiscardedContent: Bool

    Objective-C

    @property BOOL evictsObjectsWithDiscardedContent

    Discussion

    If YEStrue, the cache will evict a discardable-content object after its content is discarded. If NOfalse, it will not. The default is YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • delegate delegate Property

    The cache’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSCacheDelegate?

    Objective-C

    @property(assign) id< NSCacheDelegate > delegate

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.