| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in Mac OS X v10.6 and later. |
| Declared in | NSCache.h |
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 if garbage collection is in effect; in memory-managed code, the cache retains the item. 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. First, 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. Second, you can add, remove, and query items in the cache from different threads without having to lock the cache yourself. Lastly, retrieving something from an NSCache object returns an autoreleased result. 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.
Returns the maximum number of objects that the cache can currently hold.
- (NSUInteger)countLimit
The maximum number of objects that the cache can currently hold.
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.
NSCache.hReturns the cache’s delegate.
- (id)delegate
The application delegate object.
The delegate object is expected to conform to the NSCacheDelegate protocol.
NSCache.hReturns whether or not the cache will automatically evict discardable-content objects whose content has been discarded.
- (BOOL)evictsObjectsWithDiscardedContent
YES if the cache will evict the object after it is discarded; otherwise, NO.
By default, evictsObjectsWithDiscardedContent is set to YES.
NSCache.hReturns the name of the cache.
- (NSString *)name
The name of the cache.
Returns the empty string if no name is specified.
NSCache.hReturns the value associated with a given key.
- (id)objectForKey:(id)key
An object identifying the value.
The value associated with key, or NULL if no value is associated with key. The caller does not have to release the value returned to it.
NSCache.hEmpties the cache.
- (void)removeAllObjects
NSCache.hRemoves the value of the specified key in the cache.
- (void)removeObjectForKey:(id)key
The key identifying the value to be removed.
NSCache.hSets the maximum number of objects that the cache can hold.
- (void)setCountLimit:(NSUInteger)lim
The maximum number of objects that the cache will be allowed to hold.
Setting the count limit to a number less than or equal to 0 will have no effect on the maximum size of the cache.
NSCache.hMakes the given object the cache’s delegate.
- (void)setDelegate:(id)del
The object to be registered as the delegate.
The delegate object is expected to conform to the NSCacheDelegate protocol.
NSCache.hSets whether the cache will automatically evict NSDiscardableContent objects after the object’s content has been discarded.
- (void)setEvictsObjectsWithDiscardedContent:(BOOL)b
If YES, the cache evicts NSDiscardableContent objects after the object’s contents has been discarded; if NO the cache does not evict these objects.
NSCache.hSets the cache’s name attribute to a specific string.
- (void)setName:(NSString *)cacheName
The new name for the cache.
NSCache.hSets the value of the specified key in the cache.
- (void)setObject:(id)obj forKey:(id)key
The object to be stored in the cache.
The key with which to associate the value.
NSCache.hSets the value of the specified key in the cache, and associates the key-value pair with the specified cost.
- (void)setObject:(id)obj forKey:(id)key cost:(NSUInteger)num
The object to store in the cache.
The key with which to associate the value.
The cost with which to associate the key-value pair.
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.
NSCache.hSets the maximum total cost that the cache can have before it starts evicting objects.
- (void)setTotalCostLimit:(NSUInteger)lim
The maximum total cost that the cache can have before it starts evicting objects.
NSCache.hReturns the maximum total cost that the cache can have before it starts evicting objects.
- (NSUInteger)totalCostLimit
The current maximum cost that the cache can have before it starts evicting objects.
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.
NSCache.hLast updated: 2009-08-13
