The iOS framework that grows only as fast as its documentation
NIImageMemoryCache Class Reference

Overview

An in-memory cache for storing images with caps on the total number of pixels.

When reduceMemoryUsage is called, the least recently used images are removed from the cache until the numberOfPixels is below maxNumberOfPixelsUnderStress.

When an image is added to the cache that causes the memory usage to pass the max, the least recently used images are removed from the cache until the numberOfPixels is below maxNumberOfPixels.

By default the image memory cache has no limit to its pixel count. You must explicitly set this value in your application.

Attention
If the cache is too small to fit the newly added image, then all images will end up being removed including the one being added.
See Also
Nimbus::imageMemoryCache
Nimbus::setImageMemoryCache:
Inheritance diagram for NIImageMemoryCache:
NIMemoryCache

Tasks

Querying an In-Memory Image Cache
unsigned long long numberOfPixels property
 
Setting the Maximum Number of Pixels
unsigned long long maxNumberOfPixels property
 
unsigned long long maxNumberOfPixelsUnderStress property
 
Creating an In-Memory Cache
(id) - initWithCapacity:
 
Querying an In-Memory Cache
(NSUInteger) - count
 
Storing Objects in the Cache
(void) - storeObject:withName:
 
(void) - storeObject:withName:expiresAfter:
 
Removing Objects from the Cache
(void) - removeObjectWithName:
 
(void) - removeAllObjectsWithPrefix:
 
(void) - removeAllObjects
 
Accessing Objects in the Cache
(id) - objectWithName:
 
(BOOL) - containsObjectWithName:
 
(NSDate *) - dateOfLastAccessWithName:
 
(NSString *) - nameOfLeastRecentlyUsedObject
 
(NSString *) - nameOfMostRecentlyUsedObject
 
Reducing Memory Usage Explicitly
(void) - reduceMemoryUsage
 
Subclassing

The following methods are provided to aid in subclassing and are not meant to be used externally.

(BOOL) - shouldSetObject:withName:previousObject:
 
(void) - didSetObject:withName:
 
(void) - willRemoveObject:withName:
 
(BOOL) - willSetObject:withName:previousObject:
 

Method Documentation

numberOfPixels

Returns the total number of pixels being stored in the cache.

@property (nonatomic, readonly) unsigned long long numberOfPixels;
Discussion
Returns
The total number of pixels being stored in the cache.

maxNumberOfPixels

The maximum number of pixels this cache may ever store.

@property (nonatomic) unsigned long long maxNumberOfPixels;
Discussion

Defaults to 0, which is special cased to represent an unlimited number of pixels.

Returns
The maximum number of pixels this cache may ever store.

maxNumberOfPixelsUnderStress

The maximum number of pixels this cache may store after a call to reduceMemoryUsage.

@property (nonatomic) unsigned long long maxNumberOfPixelsUnderStress;
Discussion

Defaults to 0, which is special cased to represent an unlimited number of pixels.

Returns
The maximum number of pixels this cache may store after a call to reduceMemoryUsage.

initWithCapacity:

Initializes a newly allocated cache with the given capacity.

- (id)initWithCapacity:(NSUInteger)capacity;
Discussion
Returns
An in-memory cache initialized with the given capacity.

count

Returns the number of objects currently in the cache.

- (NSUInteger)count;
Discussion
Returns
The number of objects currently in the cache.

storeObject:withName:

Stores an object in the cache.

- (void)storeObject:(id)object withName:(NSString *)name;
Discussion

The object will be stored without an expiration date. The object will stay in the cache until it's bumped out due to the cache's memory limit.

Parameters
objectThe object being stored in the cache.
nameThe name used as a key to store this object.

storeObject:withName:expiresAfter:

Stores an object in the cache with an expiration date.

- (void)storeObject:(id)object withName:(NSString *)name expiresAfter:(NSDate *)expirationDate;
Discussion

If an object is stored with an expiration date that has already passed then the object will not be stored in the cache and any existing object will be removed. The rationale behind this is that the object would be removed from the cache the next time it was accessed anyway.

Parameters
objectThe object being stored in the cache.
nameThe name used as a key to store this object.
expirationDateA date after which this object is no longer valid in the cache.

removeObjectWithName:

Removes an object from the cache with the given name.

- (void)removeObjectWithName:(NSString *)name;
Discussion
Parameters
nameThe name used as a key to store this object.

removeAllObjectsWithPrefix:

Removes all objects from the cache with a given prefix.

- (void)removeAllObjectsWithPrefix:(NSString *)prefix;
Discussion

This method requires a scan of the cache entries.

Parameters
prefixAny object name that has this prefix will be removed from the cache.

removeAllObjects

Removes all objects from the cache, regardless of expiration dates.

- (void)removeAllObjects;
Discussion

This will completely clear out the cache and all objects in the cache will be released.

objectWithName:

Retrieves an object from the cache.

- (id)objectWithName:(NSString *)name;
Discussion

If the object has expired then the object will be removed from the cache and nil will be returned.

Returns
The object stored in the cache. The object is retained and autoreleased to ensure that it survives this run loop if you then remove it from the cache.

containsObjectWithName:

Returns a Boolean value that indicates whether an object with the given name is present in the cache.

- (BOOL)containsObjectWithName:(NSString *)name;
Discussion

Does not update the access time of the object.

If the object has expired then the object will be removed from the cache and NO will be returned.

Returns
YES if an object with the given name is present in the cache and has not expired, otherwise NO.

dateOfLastAccessWithName:

Returns the date that the object with the given name was last accessed.

- (NSDate*)dateOfLastAccessWithName:(NSString *)name;
Discussion

Does not update the access time of the object.

If the object has expired then the object will be removed from the cache and nil will be returned.

Returns
The last access date of the object if it exists and has not expired, nil otherwise.

nameOfLeastRecentlyUsedObject

Retrieve the name of the object that was least recently used.

- (NSString*)nameOfLeastRecentlyUsedObject;
Discussion

This will not update the access time of the object.

If the cache is empty, returns nil.

nameOfMostRecentlyUsedObject

Retrieve the key with the most fresh access.

- (NSString*)nameOfMostRecentlyUsedObject;
Discussion

This will not update the access time of the object.

If the cache is empty, returns nil.

reduceMemoryUsage

Removes all expired objects from the cache.

- (void)reduceMemoryUsage;
Discussion

Subclasses may add additional functionality to this implementation. Subclasses should call super in order to prune expired objects.

This will be called when UIApplicationDidReceiveMemoryWarningNotification is posted.

shouldSetObject:withName:previousObject:

An object is about to be stored in the cache.

- (BOOL)shouldSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
Discussion
Parameters
objectThe object that is about to be stored in the cache.
nameThe cache name for the object.
previousObjectThe object previously stored in the cache. This may be the same as object.
Returns
YES If object is allowed to be stored in the cache.

didSetObject:withName:

An object has been stored in the cache.

- (void)didSetObject:(id)object withName:(NSString *)name;
Discussion
Parameters
objectThe object that was stored in the cache.
nameThe cache name for the object.

willRemoveObject:withName:

An object is about to be removed from the cache.

- (void)willRemoveObject:(id)object withName:(NSString *)name;
Discussion
Parameters
objectThe object about to removed from the cache.
nameThe cache name for the object about to be removed.

willSetObject:withName:previousObject:

This method is deprecated.

- (BOOL)willSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
Discussion

Please use shouldSetObject:withName:previousObject: instead.