class DataCache in Tinman.Core.Caching

Base class for objects that implement a thread-safe and page based cache for a number of independent source data objects.

abstract class	DataCache	extends	Disposable
		implements	IBeginEndSync
			ICacheCallback<int64>
		base of	FileCache
			ObjectDataCache

Public / Attributes

HasSourceFiles

Returns if this data cache currently has one or more source data files attached to it.

public property	HasSourceFiles { get }
type	bool
value		true if at least one source data file is present, false if not.

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

MaxWeightSum

The maximum page weight sum.

public property	MaxWeightSum { get set }
type	int64
value	[>=0]	The maximum weight sum. If 0 the maximum limit is disabled.

Public / Methods

Access

Accesses a cache page.

[BeginEnd]
public method	Access (int32 sourceId, int64 sourceIndex, PageLoadFlags loadFlags = PageLoadFlags.Load)
type	int32
params	sourceId		The source ID of the source data object that contains the page to access.
	sourceIndex		The source data object page index (54-bit).
	loadFlags		The flags that determine how to load the cache page. When set to Manual, the CacheReadPage method will not be called. The calling code must load the cache page in this case. Defaults to Load.
returns			The cache page index.

Remarks:

The returned cache page can be accessed safely by the calling thread until it calls one of the following methods:

• Access,
  End,
  Flush:
  Another thread might perform a re-entrant call, causing the cache page of the calling thread to become evicted from the cache. This can be avoided by calling LockPage and UnlockPage properly.
• Release,
  SourceIdRelease:
  If the cache page is evicted by the call, it can no longer be accessed.

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Begin

Begins an access to this object.

public method	Begin ()
implements	IBeginEnd.Begin

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

CachePageChoose

When a cache page needs to be (re-)used, this method is called for each candidate until an invocation returns true.

public method	CachePageChoose (int32 pageIndex, bool partially)
type	bool
params	pageIndex		The cache page index.
	partially		Going to do partial load of cache page (see Partial)?
returns			true if the cache page will be reused, false if not.
implements	ICacheCallback.CachePageChoose

CachePageData

Performs writing and/or reading of cache page data.

public method	CachePageData (int32 pageIndex, int32 write, int64 writeId, int32 read, int64 readId)
params	pageIndex		The cache page index.
	write		Depicts how to write cache page data: <0: Do not write cache page data. 0: Unload partial page (no longer present in the cache). 1: Unload full page (no longer present in the cache). 2: Flush partial page (still present in the cache). 3: Flush full page (still present in the cache).
	writeId		The cache page ID currently loaded in pageIndex iff write is greater than or equal to 0.
	read		Depicts how to load the cache page: <0: Do not load the page. 0: Load partial page (overwrite given cache page) 1: Load full page (overwrite given cache page) 2: Finish loading of partial page (complete given cache page)
	readId		The cache page ID to load into pageIndex iff read is greater than or equal to 0.
implements	ICacheCallback.CachePageData

Remarks:

Writing must always be done first, following by cache page reading.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

End

Ends the current access to this object.

public method	End ()
implements	IBeginEnd.End

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

Flush

Flushes all dirty cache pages of the given source object.

[BeginEnd]
public method	Flush (int32 sourceId)
params	sourceId		The ID of the source data object.

See also:

SetDirty

IsDirty

Returns if the given page is dirty.

[BeginEnd]
public method	IsDirty (int32 cacheIndex)
type	bool
params	cacheIndex		The cache page index.
returns			true if the page is dirty, false if not.

See also:

SetDirty

LockPage

Locks a cache page.

[BeginEnd]
public method	LockPage (int32 cacheIndex)
params	cacheIndex		The cache page index.

Remarks:

Locked pages cannot be evicted from the cache. For each call to LockPage, the UnlockPage method must be called once to unlock the page.

See also:

UnlockPage

MakePageId

Makes a 64-bit page ID value.

[Pure]
public static method	MakePageId (int32 sourceId, int64 sourceIndex)
type	int64
params	sourceId		The 10-bit source ID value.
	sourceIndex		The 54-bit source index value.
returns			The 64-bit page ID value.

MakeSourceId

Makes a 10-bit source ID value.

[Pure]
public static method	MakeSourceId (int64 pageId)
type	int32
params	pageId		The 64-bit page ID value.
returns			The 10-bit source ID value.

MakeSourceIndex

Makes a 54-bit source index value.

[Pure]
public static method	MakeSourceIndex (int64 pageId)
type	int64
params	pageId		The 64-bit page ID value.
returns			The 54-bit source index value.

NotifyWaiting

Notifies all threads currently blocked in a call to WaitForNotify.

public method	NotifyWaiting ()
implements	IBeginEndSync.NotifyWaiting

Release

Releases a page.

[BeginEnd]
public method	Release (int32 sourceId, int64 sourceIndex)
params	sourceId		The source ID.
	sourceIndex		The source page to release.

Remarks:

If the given page is not present in the cache, the method returns silently.

---

Releases a range of source file pages.

[BeginEnd]
public method	Release (int32 sourceId, int64 sourceIndex, int64 count)
params	sourceId		The source ID.
	sourceIndex		Index of first source file page to release (54-bit).
	count		Number of source file pages to release.

Remarks:

If the given page is not present in the cache, the method returns silently.

SetDirty

Marks a cache page as dirty or not dirty.

[BeginEnd]
public method	SetDirty (int32 cacheIndex, bool dirty = true)
params	cacheIndex		The cache page index.
	dirty		Set dirty flag? Defaults to true.

SourceIdAllocate

Allocates a source ID in this cache for the given source data object.

[BeginEnd]
public method	SourceIdAllocate (IDataCacheObject sourceData)
type	int32
params	sourceData		The source data object.
returns		[1..2047]	The source ID.

See also:

SourceIdRelease

SourceIdRelease

Releases a source ID.

[BeginEnd]
public method	SourceIdRelease (int32 sourceId, bool discardDirty = false)
type	bool
params	sourceId		The source ID.
	discardDirty		Discard all dirty pages? Defaults to false.
returns			true if at least one more source is associated with this cache, false if not.

See also:

SourceIdAllocate

SourceIndex

Returns the source index of the given cache slot.

[BeginEnd]
public method	SourceIndex (int32 sourceId, int32 cacheIndex)
type	int64
params	sourceId		The source ID.
	cacheIndex		The cache page index.
returns			The source index or -1.

UnlockPage

Unlocks a cache page.

[BeginEnd]
public method	UnlockPage (int32 cacheIndex)
params	cacheIndex		The cache page index.

Remarks:

Locked pages cannot be evicted from the cache. For each call to LockPage, the UnlockPage method must be called once to unlock the page.

See also:

LockPage

WaitForNotify

Waits until one of the events described below takes place and reacquires the lock on this monitor.

public method	WaitForNotify (int32 timeout = 50)
params	timeout	[>0]	The timeout value, in milliseconds. Defaults to 50.
implements	IBeginEndSync.WaitForNotify

Remarks:

The calling thread will be blocked until one of the following events takes place:

• Another thread calls the NotifyWaiting method on this monitor.
• The timeout has elapsed.

Exceptions:

• InvalidArgumentException:
  If one of the parameters is invalid.

Weight

Updates the weight of the given cache page.

[BeginEnd]
public method	Weight (int32 pageIndex, int32 weight)
params	pageIndex		The cache page index.
	weight		The new page weight.

Protected / Attributes

pageCount

The number of cache pages.

protected readonly field	pageCount
type	int32

Protected / Constructors

DataCache

Creates a new instance of DataCache.

protected constructor	DataCache (int32 pageCount)
params	pageCount	[>0]	The number of cache pages.

Protected / Methods

ClearPage

Clears the given cache slot.

protected virtual method	ClearPage (int32 pageIndex)
params	pageIndex		Page index of cache slot to clear.

Remarks:

The GetWeight method must return 0 for cleared cache slots.

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

GetWeight

Returns the weight of the given cache slot.

protected virtual method	GetWeight (int32 pageIndex)
type	int32
params	pageIndex		Page index of cache slot.
returns		[>=0]	The page weight.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger