interface ICacheBase in Tinman.Core.Caching

Base interface for cache-like data structures.

interface	ICacheBase	with	<TId>
		base of	ICache
			SimpleCache

Remarks

The following terms are used by this interface:

• page:
  A page is a logical piece of information which is expensive to obtain or access.
• cache:
  A cache is a container that can store a number of pages and provides fast access to them.
• capacity:
  The capacity of a cache is the maximum number of pages that it can store.
• page id:
  The page ID can be used to uniquely refer to a page.
• page index:
  The page index is the storage position of the page in the cache container.

An ICacheBase object is responsible for the following tasks:

• Page loading / unloading:
  When a page is requested for the first time, it must be loaded into the cache. If all caches pages are used, the oldest page must be evicted in order to make room for the new page. The load / unload actions are not performed by the cache itself. Pages are requested via Fetch. Page can be evicted by using one of the EvictAll, EvictId and EvictIndex methods.
• Mapping of page IDs to page indices:
  For each cached paged, a mapping of the form {ID => index} is stored and maintained. The current mappings can be queried by using the GetId and GetIndex method.

Client code can use the cache page index values for storing additional data per cache page.

Attributes

Capacity

The capacity of this cache.

property	Capacity { get }
type	int32
value	[>0]	The maximum number of entries this cache can hold.

InvalidId

The page ID value that represents non-existent mappings.

property	InvalidId { get }
type	TId
value		The invalid page ID value.

Oldest

Returns the index of the oldest cache page.

property	Oldest { get }
type	int32
value	[-1..Capacity-1]	Index of the least-recently used cache page or -1 if all pages are unused.

Methods

EvictAll

Evicts all pages from the cache.

method

EvictAll ()

EvictId

Evicts the given page from the cache.

method	EvictId (TId pageId)
params	pageId		The cache page ID.

Remarks:

Requesting the given page later will cause a cache miss.

EvictIndex

Evicts the given page from the cache.

method	EvictIndex (int32 pageIndex)
params	pageIndex	[0..Capacity-1]	The cache page index.

Remarks:

Requesting the given page later will cause a cache miss.

Fetch

Fetches a page from the cache, loading it if necessary.

method	Fetch (TId pageId)
type	int32
params	pageId		The page ID.
returns			[>=0]: The page is present in the cache, the return value is its index. [<=-1]: The page is not present in the cache and shall be loaded into the cache using the page index given by -1-value, where value is the value that is returned by this method.

GetId

Returns the page ID of the given page.

method	GetId (int32 pageIndex)
type	TId
params	pageIndex	[0..Capacity-1]	The page index.
returns			The page ID.

Remarks:

The state of the cache is not modified by this method.

GetIndex

Returns the cache page index of the given page.

method	GetIndex (TId pageId, bool hitPage = false)
type	int32
params	pageId		The page ID.
	hitPage		Update state of the cache by hitting the page if it exists?
returns		[>=-1]	The cache page index or -1.

Remarks:

The state of the cache is not modified by this method if hitPage is false.

Use

The given cache page has been used.

method	Use (int32 pageIndex)
params	pageIndex	[0..Capacity-1]	The page index.

Remarks:

Use this method to avoid specific pages to get evicted from the cache too soon.