RKCache Class Reference

The RKCache class declares the programmatic interface for the RKRegex framework caching feature.

Some of the features provided by the RKCache class are:

• Only one instance of a representation of an objects 'value' (as determined by hash) can be placed in the cache at a time, similar to NSSet behavior.
• Uses NSMapTable for the backing store.
• Can be enabled or disabled at any time.
• Multithreading safe. Multiple reader, single writer locking methodology.
• Safe to add objects, remove individual objects, or clear the entire cache at any time without having to coordinate or synchronize threads.
• Uses a fast lock bypass when single threaded which automatically switches to full multithreaded atomic semantics as soon as isMultiThreaded returns YES

While a RKCache will permit any type of object to be added, as a pragmatic limitation only immutable objects should be added to a cache. In essence, a RKCache is a multithreading safe NSMutableSet. The cache can only ensure that an object retrieved from the cache will not be deallocated before the retrieving thread has finished with the object and released it properly. Once an object has been retrieved, the retrieved object must provide any concurrent modification safety mechanisms. Since immutable objects can not be modified by definition, this greatly simplifies concurrent access to objects and is the reason why only immutable objects should be added in general.

A RKCache is best applied to situations in which a result can take an appreciable amount of time to prepare, but once computed, the result can be used again and again. For example, the RegexKit.framework must compile a regular expression to an internal format before it can perform any matches with it. The compiled regular expression does not change, and can be reused again and again. While compiling a regular expression is relatively quick, it can still be an order of magnitude slower than a cache lookup.

When an object is added to the cache, it is sent a retain message just as if it were being added to any other type of collection. Similarly, when an object is removed from the cache, it is sent a release message. Adding or removing objects from the cache requires the thread to obtain the exclusive use write lock on the cache. There can be any number of simultaneous threads with a read lock, but the write lock guarantees that the write lock owner is the only thread accessing the cache.

The cache takes certain steps to ensure that objects are not deallocated while in use even if another thread immediately clears the cache after the requesting thread has retrieved an object. To do this, the cache obtains a read lock on the NSMapTable and performs a lookup. If there is a match, the cache sends a retain message to the retrieved object while it still has the cache read locked and then releases its read lock. A different thread might immediately obtain a write lock on the cache and clear it, causing the cache to release ownership of the just retrieved object. Since the cache sent a retain message to the just retrieved object, it is not immediately deallocated. If the caller requests it, the cache sends an autorelease to the object before returning it.

Each thread is required to have at least one NSAutoreleasePool. Since the autorelease is registered with the retrieving threads NSAutoreleasePool, this ensures that the object will not be deallocated until the requesting threads NSAutoreleasePool is released. A caller might request that an autorelease not be sent automatically after the object was retrieved because it will be returning the result as part of an init... method and would have to counter the autorelease with another retain message immediately, wasting effort.