class ObjectDataCache in Tinman.Core.Caching

Base class for data caches that hold an object per cache slot.

class	ObjectDataCache	with	<TObject>	as	class
		extends	DataCache

Remarks

IDisposable objects in cache slots are Dispose d when the cache slot is cleared.

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.
inherited	DataCache.HasSourceFiles

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.
inherited	DataCache.MaxWeightSum

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.
inherited	DataCache.Access

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 ()
inherited	DataCache.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.
inherited	DataCache.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.
inherited	DataCache.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 ()
inherited	DataCache.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.
inherited	DataCache.Flush

See also:

DataCache.SetDirty

Get

public method	Get (int32 pageIndex)
type	TObject
params	pageIndex

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.
inherited	DataCache.IsDirty

See also:

DataCache.SetDirty

LockPage

Locks a cache page.

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

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:

DataCache.UnlockPage

NotifyWaiting

Notifies all threads currently blocked in a call to WaitForNotify.

public method	NotifyWaiting ()
inherited	DataCache.NotifyWaiting

Release

Releases a page.

[BeginEnd]
public method	Release (int32 sourceId, int64 sourceIndex)
params	sourceId		The source ID.
	sourceIndex		The source page to release.
inherited	DataCache.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.
inherited	DataCache.Release

Remarks:

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

Set

public method	Set (int32 pageIndex, [Owner] TObject obj)
params	pageIndex
	obj

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.
inherited	DataCache.SetDirty

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.
inherited	DataCache.SourceIdAllocate

See also:

DataCache.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.
inherited	DataCache.SourceIdRelease

See also:

DataCache.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.
inherited	DataCache.SourceIndex

UnlockPage

Unlocks a cache page.

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

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:

DataCache.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.
inherited	DataCache.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.
inherited	DataCache.Weight

Protected / Attributes

pageCount

The number of cache pages.

protected readonly field	pageCount
type	int32
inherited	DataCache.pageCount

Protected / Constructors

ObjectDataCache

Creates a new instance of ObjectDataCache.

protected constructor	ObjectDataCache (int32 pageCount, int64 maxWeightSum = 0)
params	pageCount	[>0]	The cache page count.
	maxWeightSum	[>=0]	The maximum weight sum. If 0 the maximum limit is disabled. Defaults to 0.

Protected / Methods

ClearPage

Clears the given cache slot.

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

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	DataCache.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 override method	GetWeight (int32 pageIndex)
type	int32
params	pageIndex		Page index of cache slot.
returns		[>=0]	The page weight.
overrides	DataCache.GetWeight