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:

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

object	The object being stored in the cache.
name	The 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

object	The object being stored in the cache.
name	The name used as a key to store this object.
expirationDate	A 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

name	The 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

prefix

Any 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

object	The object that is about to be stored in the cache.
name	The cache name for the object.
previousObject	The 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

object	The object that was stored in the cache.
name	The 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

object	The object about to removed from the cache.
name	The 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.