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.

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.

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.