NIMemoryCache Class Reference

Overview

An in-memory cache for storing objects with expiration support.

The Nimbus in-memory object cache allows you to store objects in memory with an expiration date attached. Objects with expiration dates drop out of the cache when they have expired.

Inheritance diagram for NIMemoryCache:

Tasks
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

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.