NSCache Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 4.0 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:

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.

- (NSUInteger)countLimit
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 iOS 4.0 and later.
Declared In
NSCache.h

delegate

Returns the cache’s delegate.

- (<NSCacheDelegate>)delegate
Return Value

The application delegate object.

Discussion

The delegate object is expected to conform to the NSCacheDelegate protocol.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

evictsObjectsWithDiscardedContent

Returns whether or not the cache will automatically evict discardable-content objects whose content has been discarded.

- (BOOL)evictsObjectsWithDiscardedContent
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 iOS 4.0 and later.
Declared In
NSCache.h

name

Returns the name of the cache.

- (NSString *)name
Return Value

The name of the cache.

Discussion

Returns the empty string if no name is specified.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
NSCache.h

objectForKey:

Returns the value associated with a given key.

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

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

removeAllObjects

Empties the cache.

- (void)removeAllObjects
Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

removeObjectForKey:

Removes the value of the specified key in the cache.

- (void)removeObjectForKey:(id)key
Parameters
key

The key identifying the value to be removed.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

setCountLimit:

Sets the maximum number of objects that the cache can hold.

- (void)setCountLimit:(NSUInteger)lim
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 iOS 4.0 and later.
Declared In
NSCache.h

setDelegate:

Makes the given object the cache’s delegate.

- (void)setDelegate:(<NSCacheDelegate>)del
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 iOS 4.0 and later.
See Also
Declared In
NSCache.h

setEvictsObjectsWithDiscardedContent:

Sets whether the cache will automatically evict NSDiscardableContent objects after the object’s content has been discarded.

- (void)setEvictsObjectsWithDiscardedContent:(BOOL)b
Parameters
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

setName:

Sets the cache’s name attribute to a specific string.

- (void)setName:(NSString *)cacheName
Parameters
cacheName

The new name for the cache.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
NSCache.h

setObject:forKey:

Sets the value of the specified key in the cache.

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

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

setObject:forKey:cost:

Sets 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
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 iOS 4.0 and later.
Declared In
NSCache.h

setTotalCostLimit:

Sets the maximum total cost that the cache can have before it starts evicting objects.

- (void)setTotalCostLimit:(NSUInteger)lim
Parameters
lim

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

Availability
  • Available in iOS 4.0 and later.
Declared In
NSCache.h

totalCostLimit

Returns the maximum total cost that the cache can have before it starts evicting objects.

- (NSUInteger)totalCostLimit
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 iOS 4.0 and later.
Declared In
NSCache.h