# GSCache class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Copyright: (C) 2005 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the GSCache class
2. Software documentation for the GSCacheDelegate protocol

# Software documentation for the GSCache class

## GSCache : NSObject

> Declared in:
>   GSCache.h

The GSCache class is used to maintain a cache of objects in memory for relatively rapid access.
Typical usage might be to keep the results of a database query around for a while in order to re-use them... for instance when application configuration is obtained from a database which might be updated while the application is running.
When the cache is full, old objects are removed to make room for new ones on a least-recently-used basis.
Cache sizes may be limited by the number of objects in the cache, or by the memory used by the cache, or both. Calculation of the size of items in the cache is relatively expensive, so caches are only limited by number of objects in the default case.
Objects stored in the cache may be given a limited lifetime, in which case an attempt to fetch an expired object from the cache will cause it to be removed from the cache instead (subject to control by the delegate).
Cache keys may be objects of any type as long as they are copyable (and the copied keys are immutable) and implement the -hash and -isEqual: methods such that any two keys can be tested for equality and used as dictionary keys.
For object sizing we use the -sizeInBytesExcluding: method, which is declared in the GNUstep-base additions library headers as follows:
- (NSUInteger) sizeInBytesExcluding: (NSHashTable*)exclude;
If you wish to store objects in a size-limited cache, you should implement that method to return an appropriate size for the object you are caching.
NB. GSCache currently does not support subclassing... use it as is or extend it via categories, but do not try to add instance variables.
Method summary

- +allInstances
- +description
- -currentObjects
- -currentSize
- -delegate
- -description
- -lifetime
- -maxObjects
- -maxSize
- -name
- -objectForKey:
- -purge
- -refreshObject:forKey:lifetime:
- -setDelegate:
- -setLifetime:
- -setMaxObjects:
- -setMaxSize:
- -setName:
- -setName:forConfiguration:
- -setObject:forKey:
- -setObject:forKey:lifetime:
- -setObject:forKey:until:
- -shrinkObjects:andSize:

### allInstances

+ (NSArray*) allInstances;
Return all the current cache instances... useful if you want to do something to all cache instances in your process.

### description

+ (NSString*) description;
Return a report on all GSCache instances... calls the [GSCache -description] method of the individual cache instances to get a report on each one.

### currentObjects

- (unsigned) currentObjects;
Return the count of objects currently in the cache.

### currentSize

- (NSUInteger) currentSize;
Return the total size of the objects currently in the cache.
NB. Object sizes are considered independently... so where cached objects are containers with common content, the size of the cache may appear larger than is actually used.
Also, this figure does not consider memmory used by the cache itself or by the keys, only the memory used by the objects cached.

### delegate

- (id) delegate;
Return the delegate object previously set using the -setDelegate: method.

### description

- (NSString*) description;
Returns a string describing the status of the receiver for debug/reporting.

### lifetime

- (unsigned) lifetime;
Return the default lifetime for items set in the cache.
A value of zero means that items are not purged based on lifetime.

### maxObjects

- (unsigned) maxObjects;
Return the maximum number of items in the cache.
A value of zero means there is no limit.

### maxSize

- (NSUInteger) maxSize;
Return the maximum total size of items in the cache.
A value of zero means there is no limit.

### name

- (NSString*) name;
Return the name of this instance (as set using -setName:forConfiguration:)

### objectForKey:

- (id) objectForKey: (id)aKey;
Return the cached value for the specified key, or `nil` if there is no value in the cache.

### purge

- (void) purge;
Remove all items whose lifetimes have passed (if lifetimes are in use for the cache).

### refreshObject: forKey: lifetime:

- (id) refreshObject: (id)anObject forKey: (id)aKey lifetime: (unsigned)lifetime;
Similar to -setObject:forKey:lifetime: but, if there is an existing object in the cache which -isEqual: to anObject (or is anObject is `nil`), the existing object is retained in the cache (though its lifetime is updated/refreshed).
The value of the object in the cache is returned.

### setDelegate:

- (void) setDelegate: (id)anObject;
Sets the delegate for the receiver.
The delegate object is not retained.
If a delegate it set, it will be sent the messages in the (GSCacheDelegate) protocol (if it implements them ... which it does not need to do).

### setLifetime:

- (void) setLifetime: (unsigned)max;
Sets the default lifetime (seconds) for items added to the cache. If this is set to zero then items are not removed from the cache based on lifetimes when the cache is full and an object is added, though expired items are still removed when an attempt to retrieve them is made.

### setMaxObjects:

- (void) setMaxObjects: (unsigned)max;
Sets the maximum number of objects in the cache. If this is non-zero then an attempt to set an object in a full cache will result in the least recently used item in the cache being removed.

### setMaxSize:

- (void) setMaxSize: (NSUInteger)max;
Sets the maximum total size for objects in the cache. If this is non-zero then an attempt to set an object whose size would exceed the cache limit will result in the least recently used items in the cache being removed.

### setName:

- (void) setName: (NSString*)name;
Calls -setName:forConfiguration: to have the receiver configured by calling configuration methods rather than by using the defaults system.

### setName: forConfiguration:

- (void) setName: (NSString*)name forConfiguration: (BOOL)useDefaults;
Sets the name of this instance and whether the instance is to be configured using information from the user defaults system.
If useDefaults is `YES`, values from the user defaults system will be used to override the -setLifetime: -setMaxObjects: and -setMaxSize: methods.
The defaults keys for the configurationm are GSCacheLifetimeX, GSCacheMaxObjectsX and GSCacheMaxSizeX where X is the name of the cache being configured (an empty string for caches with no name).

### setObject: forKey:

- (void) setObject: (id)anObject forKey: (id)aKey;
Sets (or replaces) the cached value for the specified key.
The value of anObject may be `nil` to remove any cached object for aKey.

### setObject: forKey: lifetime:

- (void) setObject: (id)anObject forKey: (id)aKey lifetime: (unsigned)lifetime;
Sets (or replaces) the cached value for the specified key, giving the value the specified lifetime (in seconds). A lifetime of zero means that the item is not limited by lifetime.
The value of anObject may be `nil` to remove any cached object for aKey.

### setObject: forKey: until:

- (void) setObject: (id)anObject forKey: (id)aKey until: (NSDate*)expires;
Sets (or replaces) the cached value for the specified key, giving the value the specified expiry date. Calls -setObject:forKey:lifetime: to do the real work... this is just a convenience method to handle working out the lifetime in seconds.
If expires is `nil` or not in the future, this method simply removes the cache entry for aKey. If it is many years in the future, the item is set in the cache so that it is not limited by lifetime.

### shrinkObjects: andSize:

- (void) shrinkObjects: (unsigned)objects andSize: (NSUInteger)size;
Called by -setObject:forKey:lifetime: to make space for a new object in the cache (also when the cache is resized).
This will, if a lifetime is set (see the -setLifetime: method) first purge all expired objects from the cache, then (if necessary) remove objects from the cache until the number of objects and size of cache meet the limits specified.
If the objects argument is zero then all objects are removed from the cache.
The size argument is used only if a maximum size is set for the cache.

# Software documentation for the GSCacheDelegate protocol

## GSCacheDelegate

> Declared in:
>   GSCache.h

This protocol defines the messages which may be sent to a delegate of a GSCache object. The messages are only sent if the delegate actually implements them, so a delegate does not need to actually conform to the protocol.
Method summary

- -mayRefreshItem:withKey:lifetime:after:
- -shouldKeepItem:withKey:lifetime:after:

### mayRefreshItem: withKey: lifetime: after:

- (void) mayRefreshItem: (id)anObject withKey: (id)aKey lifetime: (unsigned)lifetime after: (unsigned)delay;
Alerts the delegate to the fact that anObject, which was cached using aKey and will expire delay seconds in the future has been looked up now, and needs to be refreshed if it is not to expire from the cache.
This is called the first time an attempt is made to access the cached value for aKey and the object is found in the cache but more than half its lifetime has expired.
The delegate method (if implemented) may replace the item in the cache immediately, or do it later asynchronously, or may simply take no action.

### shouldKeepItem: withKey: lifetime: after:

- (BOOL) shouldKeepItem: (id)anObject withKey: (id)aKey lifetime: (unsigned)lifetime after: (unsigned)delay;
Asks the delegate to decide whether anObject, which was cached using aKey and expired delay seconds ago should still be retained in the cache.
This is called when an attempt is made to access the cached value for aKey and the object is found in the cache but it is no longer valid (has expired).
If the method returns `YES`, then anObject will not be removed as it normally would. This allows the delegate to change the cached item or refresh it.
For instance, the delegate could replace the object in the cache before returning `YES` in order to update the cached value when its lifetime has expired.
Another possibility would be for the delegate to return `YES` (in order to continue using the existing object) and queue an asynchronous database query to update the cache later. In this case the expiry time of the item will be reset relative to the current time, based upon its original lifetime.