# GSCache class documentation

### Authors

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

Version: 36997

Date: 2013-08-21 09:47:28 +0100 (Wed, 21 Aug 2013)

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

### Contents -

1. Software documentation for the GSCache class
2. Software documentation for the NSObject(GSCacheSizeInBytes) category
3. 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.
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
- -setDelegate:
- -setLifetime:
- -setMaxObjects:
- -setMaxSize:
- -setName:
- -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.

### 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 tital 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:)

### 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).

### 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 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;
Sets the name of this instance.

### 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 NSObject(GSCacheSizeInBytes) category

## NSObject(GSCacheSizeInBytes)

> Declared in:
>   GSCache.h

This category declares the -sizeInBytes: method which is used by GSCache to ask objects for their size when adding them to a cache which has a limited size in bytes.

The NSObject implementation of this method is intended to provide a rough estimnate of object size which subclasses may refine in order to provide more accurate sizing information.
Subclasses should call the superclass implementation and use the resulting size information (if it is zero then the object is in the exclude set and the subclass implementation should also return zero) as a starting point on which to add the sizes of any objects contained.

For example:

     - (NSUInteger) sizeInBytes: (NSMutableSet*)exclude
     {
       NSUInteger size = [super sizeInBytes: exclude];
       if (size > 0)
         {
           size += [myInstanceVariable sizeInBytes: exclude];
         }
       return size;
     }

The performance library contains implementations giving reasonable size estimates for several common classes:

- NSArray
- NSData
- NSDictionary
- NSSet
- NSString
- GSMimeDocument (if built with the GNUstep base library)

The default ([NSObject]) implementation provides a reasonable size for any class whose instance variables do not include other objects or pointers to memory allocated on the heap.

Method summary

- -sizeInBytes:

### sizeInBytes:

- (NSUInteger) sizeInBytes: (NSMutableSet*)exclude;
If the receiver is a member of the exclude set, this method simply returns zero. Otherwise, the receiver adds itsself to the exclude set and returns its own size in bytes (the size of the memory used to hold all the instance variables defined for the receiver's class including all superclasses).

# 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.