Cache

Clear ContainsAutoPurgeable Finalize FinishRenumbering FlushByKey FlushByKeyAndSubkey

GetCacheEntry Init InitialExtraSize NewCacheEntry Purging ReleaseCacheEntry

Attributes

Class Cache defines no new attributes.

Fields

instance Cache tag;
    lgSlotCount: 0;
     entryCount: 0;
          mutex: nilObject;
end instance;

Define Class Cache;
    inherits from Object, AutoPurgeableOwner, HasReinitialize, RenumberingSensitive;
    uses extra list: Object;

    field lgSlotCount: Unsigned;
        // base-2 logarithm of number of slots in the table
    field entryCount: Unsigned;
        // total number of entries in table
    field mutex: Semaphore;
        // simplistic approach to multi-thread access to the cache

    // caching objects

    operation NewCacheEntry(key: Object; subkey: Unsigned; value: Cachable), noFail;
        // Associate the ordered pair (key, subkey) with value in the cache.
        // The cache takes over ownership of value and will destroy it in the future.
        // Any previous value associated with (key, subkey) is destroyed; it is
        // illegal to call this if the entry (key, subkey) is currently locked.
        // The value must not already be checked into this or any other cache.
        // The value must inherit from the Cachable mixin.
        // The cache does not own the keys; it does not perform anything other than
        // equality comparisons on the keys and subkeys.
        // It is illegal to call this method while any Cache routine is executing;
        // in particular, don't call this method from the memory manager's heap purger.

    operation GetCacheEntry(key: Object; subkey: Unsigned): Cachable, noFail;
        // Return the object associated with (key, subkey) in the cache or nilObject if not found.
        // If found, the entry is locked in the cache, and each GetCacheEntry that returns a
        // non-nil value must be balanced by a ReleaseCacheEntry to unlock the cache entry.
        // An entry may be locked several times, in which case it is unlocked only after the
        // corresponding number of ReleaseCacheEntry calls.
        // The caller must not alter or destroy the object returned by GetCacheEntry.
        // Cache "locking" is not related in any way to memory manager block "locking".

    operation ReleaseCacheEntry(key: Object; subkey: Unsigned; value: Cachable), noFail;
        // Unlock the cache entry, balancing a GetCacheEntry call; key and subkey should be as
        // passed to GetCacheEntry, and value should be the result from GetCacheEntry.
        // If the entry's lock count goes down to zero, the cache may destroy it or make it purgeable.
        // If value is nil, this call does nothing.

    // flushing cache objects

    operation FlushByKeyAndSubkey(key: Object; subkey: Unsigned), noFail;
        // Delete the entry, if any, in the cache associated with (key, subkey).
        // It is illegal to call this on a locked cache entry (the debug version will complain
        // about this).

    operation FlushByKey(key: Object), noFail;
        // Delete all entries in the cache associated with (key, *).
        // It is illegal to call this if any of the entries that would be deleted is locked
        // (the debug version will complain about this).

    operation Clear(), noFail;
        // Delete all entries in the cache.
        // It is illegal to call this if there are any locked entries in the cache
        // (the debug version will complain about this).

    // purging

    overrides Purging;
        // removes entries with matching value from cache

#ifdef DEBUG
    overrides ContainsAutoPurgeable;
        // checks whether cache contains <candidate> as a value of any entry
#endif

    overrides FinishRenumbering;
        // rehashes the cache after references have been renumbered

    // other

    overrides Init, InitialExtraSize;
    overrides Finalize;
end class;