NSCache Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in OS X v10.6 and later. |
| Declared in | NSCache.h |
Overview
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
NSCacheclass 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
NSMutableDictionaryobject, 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.
Tasks
Modifying the Cache Name
Getting a Cached Value
Adding and Removing Cached Values
Managing Cache Size
Managing Discardable Content
Managing the Delegate
Instance Methods
countLimit
Returns the maximum number of objects that the cache can currently hold.
Return Value
The maximum number of objects that the cache can currently hold.
Discussion
By default, countLimit will be set to 0. Any countLimit less than or equal to 0 has no effect on the number of allowed entries in the cache. This limit is not a strict limit, and if the cache goes over the limit, an object in the cache could be evicted instantly, later, or possibly never, all depending on the implementation details of the cache.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hdelegate
Returns the cache’s delegate.
Return Value
The application delegate object.
Discussion
The delegate object is expected to conform to the NSCacheDelegate protocol.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hevictsObjectsWithDiscardedContent
Returns whether or not the cache will automatically evict discardable-content objects whose content has been discarded.
Return Value
YES if the cache will evict the object after it is discarded; otherwise, NO.
Discussion
By default, evictsObjectsWithDiscardedContent is set to YES.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCache.hname
Returns the name of the cache.
Return Value
The name of the cache.
Discussion
Returns the empty string if no name is specified.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hobjectForKey:
Returns the value associated with a given key.
Parameters
- key
An object identifying the value.
Return Value
The value associated with key, or nil if no value is associated with key.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCache.hremoveAllObjects
Empties the cache.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hremoveObjectForKey:
Removes the value of the specified key in the cache.
Parameters
- key
The key identifying the value to be removed.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetCountLimit:
Sets the maximum number of objects that the cache can hold.
Parameters
- lim
The maximum number of objects that the cache will be allowed to hold.
Discussion
Setting the count limit to a number less than or equal to 0 will have no effect on the maximum size of the cache.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetDelegate:
Makes the given object the cache’s delegate.
Parameters
- del
The object to be registered as the delegate.
Discussion
The delegate object is expected to conform to the NSCacheDelegate protocol.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetEvictsObjectsWithDiscardedContent:
Sets whether the cache will automatically evict NSDiscardableContent objects after the object’s content has been discarded.
Parameters
- b
If
YES, the cache evictsNSDiscardableContentobjects after the object’s contents has been discarded; ifNOthe cache does not evict these objects.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetName:
Sets the cache’s name attribute to a specific string.
Parameters
- cacheName
The new name for the cache.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetObject:forKey:
Sets the value of the specified key in the cache.
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.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.hsetObject:forKey:cost:
Sets the value of the specified key in the cache, and associates the key-value pair with the specified cost.
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.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCache.hsetTotalCostLimit:
Sets the maximum total cost that the cache can have before it starts evicting objects.
Parameters
- lim
The maximum total cost that the cache can have before it starts evicting objects.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSCache.htotalCostLimit
Returns the maximum total cost that the cache can have before it starts evicting objects.
Return Value
The current maximum cost that the cache can have before it starts evicting objects.
Discussion
The default value is 0, which means there is no limit on the size of the cache. If 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 could automatically evict some of its objects until its total cost falls below totalCostLimit. The order in which the cache evicts objects is not guaranteed. This limit 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.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCache.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-05-01)