The Duwamish Books, Phase 4 Cache Object API Reference

Robert Coleridge
Microsoft Developer Network

August 1999

Introduction

The d4cache COM component for Phase 4 contains one class: Cache. This reference contains three sections: methods, properties, and enumerated values. For further details on the design and implementation details of the object, see my article "Creating a Page Cache Object."

Quick Reference

Method	Description
Add	Add an item (key, value pair) to the cache.
Clear	Clear all items from the cache.
CreateGeneralIndex	Used to create a general index based on specified values.
EnumHitRange	Specify the range used when enumerating based on hit counts.
Flush	Flush old items from the cache.
Initialize	Initialize the cache to a specified size.
Remove	Remove a specified item from the cache.

Property	Description
CacheEnabled	A flag determining whether caching can occur.
Count	The number of items in the cache.
EnumBy	An enumerated value determining what sort order is used to enumerate through the cache.
EnumType	An enumerated value determining what information is returned when enumerating through the cache.
Err	The last known error value.
EventsEnabled	A flag determining whether events will be fired.
FlushEnabled	A flag determining whether flushing can occur.
FlushDeltaTime	The time by which items are flushed from the cache.
Hits	The hit count belonging to a particular cached item, specified by the item's key value.
HitsOrd	The hit count belonging to a particular cached item, specified by the item's index value.
Key	The key associated with a particular cached item.
LastIndex	The index of the last access cache item.
Value	The value or data belonging to a particular cached item, specified by the item's key value.
ValueOrd	The value or data belonging to a particular cached item, specified by the item's index value.
RaiseErrors	A flag determining whether COM errors can be raised.
EnumSorted	An enumerated value determining what sort order is used to enumerate through the cache.

Enumerated type	Description
ENUMBY	A list of values used to determine the sort order of the cache.
ENUMTYPES	A list of values used to determine the information returned during enumeration of the cache.
SORTON	A list of values used to determine the key used in the general index sort.

Events	Description
CacheClearing	Fired when the cache is being cleared.
CacheCleared	Fired when a clear ends.
CacheExtending	Fired when the cache is being extended.
CacheExtended	Fired when a cache extension is finished.
CacheFlushing	Fired when a flush begins.
CacheFlushed	Fired when a flush ends.
CacheSorting	Fired when the cache is being sorted.
CacheSorted	Fired when a sort ends.
ItemAdded	Fired when an item is added to the cache.

Methods

Add

Adds an item and its associated unique key to the cache.

Interface syntax

object.Add Key,Value

–or–

Boolean = object.Add(Key, Value)

Parameters

Key: Associated unique key for item.

Value: String to be stored.

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   oCache.Add "Key", "This is the item data"
End if

Remarks

This function returns a Boolean flag depicting success or failure.

Remove

Removes a specified item from the cache.

Interface syntax

object.Remove sKey

–or–

Boolean = object.Remove(sKey)

Parameters

Key: Associated unique key for item to be removed.

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   oCache.Remove "Key"
End if

Remarks

This function returns a Boolean flag depicting success or failure.

Clear

Clears out the internal cache.

Interface syntax

object.Clear

–or–

Boolean = object.Clear()

Parameters

None

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added / manipulated
   oCache.Clear
End if

Remarks

This function returns a Boolean flag depicting success or failure.

Initialize

Initializes the internal structures of the cache.

Interface syntax

object.Initialize SizeOfCache[, GrowBy]

–or–

Boolean = object.Initialize(SizeOfCache[, GrowBy])

Parameters

SizeOfCache: The initial number of items that can be stored in the cache.

GrowBy: The number of elements the cache is to grow each time it fills up.

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
End if

Remarks

This function returns a Boolean flag depicting success or failure.

Flush

Flushes out the cache according to preset parameters. Similar to the Clear method but removes only those items that exceed the preset parameters, such as tie in cache.

Interface syntax

object.Flush

–or–

Boolean = object.Flush()

Parameters

None

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   oCache.Flush
End if

Remarks

This function returns a Boolean flag depicting success or failure.

CreateGeneralIndex

Creates a generalized index based on specified values.

Interface syntax

object.CreateGeneralIndex(SortOn)

–or–

Boolean = object.CreateGeneralIndex(SortOn)

Parameters

SortOn: The sort parameter based on SORTON values.

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   oCache.CreateGeneralIndex(icSORT_KEY)
End if

Remarks

This function returns a Boolean flag depicting success or failure.

Properties

Key

Returns the unique key associated with the specified index in the cache.

Interface syntax

sKey = object.Key(n)

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print oCache.Key(1)
End if

Value

Returns the value associated with the specified key.

Interface syntax

Value = object.Item(sKey)

–or–

Value = object(sKey)

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print oCache.Value("Key")
   ' or using the default method
   Debug.Print oCache("Key")
End if

ValueOrd

Returns the value associated with the specified index.

Interface syntax

Value = object.Value(lIndex)

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print oCache.ValueOrd(123)
End if

Remarks

This function returns the same data as the Value property except that the data is accessed ordinally rather than by the associated key.

Hits

Returns the hit count associated with the specified key.

Interface syntax

Value = object.Hits(sKey)

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print oCache.Hits("Key")
End if

HitsOrd

Returns the hit count associated with the specified index.

Interface syntax

Value = object.HitsOrd(lIndex)

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print oCache.HitsOrd(123)
End if

Remarks

This function returns the same hit count as the Hit property except that the data is accessed ordinally rather than by the associated key.

Count

Returns the number of items in the cache.

Interface syntax

n = object.Count

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print "There are " & oCache.Count & " objects in the cache"
End if

RaiseErrors

Sets or resets the flag that determines the type of error traps raised.

Interface syntax

flag = object.RaiseErrors

–or–

object.RaiseErrors boolean

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   oCache,RaiseErrors = False
   oCache.Add "Key", "This is the item data"
   'add again to demonstrate
   oCache.Add "Key", "This is the item data"
   'no error raised since turned off therefore must check err value
   If oCache.Err then
      Debug.Print "A duplicate key error would have occurred"
   End if
   oCache,RaiseErrors = True
   On Error Resume Next
   oCache.Add "Key", "This is the item data"
   'add again to demonstrate
   oCache.Add "Key", "This is the item data"
   'an error would be raised and must be trapped for
   If Err then
      Debug.Print "A duplicate key error would have occurred"
   End if
End if

Remarks

Set this property to true when the cache is used in a scripting language to prevent raising of untrappable errors.

FlushDeltaTime

Sets or obtains the flush delta time-out.

Interface syntax

n = object.FlushDeltaTime

–or–

object.FlushDeltaTime = n

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
oCache.FlushDeltaTime = 20 ' 20 seconds
If oCache.Initialize(2000) then
   '… cache values added
   'do some lengthy work that exceeds the specified timeout . . .
   oCache.Add "new key", "Item data"
   'When the preceding add took place the the cache
   'would have been flushed of any data older than 20 seconds
End if

Remarks

The time is given in milliseconds.

EnumSorted

Sets or obtains the sort order for the enumeration done by the _NewEnum interface.

Interface syntax

n = object.EnumSorted

–or–

object. EnumSorted = n

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
Dim v As Variant
oCache.EnumSorted = icENUM_DESCENDING_ACCESS_TIME 
If oCache.Initialize(2000) then
   '… cache values added
   'The following will iterate through the cache
   'going from oldest to newest
   For Each v In oCache
      Debug.Print v
   Next v
End if

Remarks

This property utilizes the ENUMBY enumerated constants, which are defined as follows:

icENUM_NONSORTED: The data returned from the _NewEnum interface is returned in an implementation-derived sequence and therefore cannot be guaranteed to be in any order.

icENUM_ASCENDING_KEY: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the keys associated with each item.

icENUM_DESCENDING_KEY: The data returned from the _NewEnum interface is sorted in a descending sequence based on the keys associated with each item.

icENUM_ASCENDING_INDEX: The data returned from the _NewEnum interface is returned in a forward sequence and is simply the index values of the actual key index.

icENUM_DESCENDING_INDEX: The data returned from the _NewEnum interface is returned in a reverse sequence and is simply the index values of the actual key index.

icENUM_ASCENDING_ACCESS_TIME: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the access time of each item.

icENUM_DESCENDING_ACCESS_TIME: The data returned from the _NewEnum interface is sorted in a descending sequence based on the access time of each item.

icENUM_GI_ASCENDING_HITCOUNT: The data returned from the _NewEnum interface is sorted in the general index in ascending sequence based on the hit count of each item.

icENUM_GI_DESCENDING_HITCOUNT: The data returned from the _NewEnum interface is sorted in the general index in descending sequence based on the hit count of each item.

LastIndex

Obtains the index ID for the last item accessed.

Interface syntax

n = object.LastIndex

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
Dim v As Variant
oCache.EnumSorted = icENUM_DESCENDING_ACCESS_TIME 
If oCache.Initialize(2000) then
   '… cache values added
   'The following will iterate through the cache
   'going from oldest to newest
   For Each v In oCache
      Debug.Print v, oCache.LastIndex
   Next v
End if

EnumType

Sets or obtains the enumeration type for the _NewEnum interface.

Interface syntax

n = object.EnumType

–or–

object. EnumType = n

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
Dim v As Variant
oCache.EnumSorted = icENUM_ASCENDING_ACCESS_TIME 
oCache.EnumType = icENUM_VALUE
If oCache.Initialize(2000) then
   '… cache values added
   'The following will iterate through the cache
   'and retreive the associated value
   For Each v In oCache
      Debug.Print v
   Next v
End if

Remarks

This property utilizes the ENUMTYPES enumerated constants, which are defined as follows:

icENUM_HITCOUNT: The data returned from the _NewEnum interface is the hit count for the relevant item.

icENUM_KEY: The data returned from the _NewEnum interface is the key that was stored with the Add method.

icENUM_VALUE: The data returned from the _NewEnum interface is the value or data that was stored with the Add method.

Err

Obtains the value of the last known error.

Interface syntax

n = object.Err

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   oCache,RaiseErrors = False
   oCache.Add "Key", "This is the item data"
   'add again to demonstrate
   oCache.Add "Key", "This is the item data"
   'no error raised since turned off therefore must check err value
   If oCache.Err then
      Debug.Print "A duplicate key error would have occurred"
   End if
   oCache,RaiseErrors = True
   On Error Resume Next
   oCache.Add "Key", "This is the item data"
   'add again to demonstrate
   oCache.Add "Key", "This is the item data"
   'an error would be raised and must be trapped for
   If Err then
      Debug.Print "A duplicate key error would have occurred"
   End if
End if

Remarks

This value is reset to 0 upon entry to all methods and relevant properties. The value contained, if non-zero, indicates an error.

FlushEnabled

Sets or obtains a flag that determines whether flushing will occur.

Interface syntax

n = object.FlushEnabled

–or–

object.FlushEnabled = n

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
oCache.FlushDeltaTime = 20 ' 20 seconds
oCache.FlushEnabled = False
If oCache.Initialize(2000) then
   '… cache values added
   'do some lengthy work that exceeds the specified timeout . . .
   oCache.Add "new key", "Item data"
   'When the preceding add took place the the cache
   'would have been flushed of any data older than 20 seconds
   'but since flushing was disabled all data reamins in the cache.
End if

Remarks

One of the uses for this property is in front-end loading of the cache. With this property it is possible to load the cache before it is required and then turn flushing back on, because flushing only takes place on cache addition.

CacheEnabled

Sets or obtains a flag that determines whether caching will occur.

Interface syntax

n = object.CacheEnabled

–or–

object.CacheEnabled = n

Remarks

Setting this flag to false will cause all subsequent calls to the Add method to fail until caching is turned back on.

EventsEnabled

Sets or obtains a flag that determines whether events are fired.

Interface syntax

n = object.EventsEnabled

–or–

object.EventsEnabled = n

Visual Basic example

Dim oCache as new MSDNContainer.D4Cache
If oCache.Initialize(2000) then
   '… cache values added
   Debug.Print "There are " & oCache.Count & " objects in the cache"
Else
   Debug.print oCache.Err
End if

Remarks

The internal value is reset on each method call to the object.

Enumerated Types

ENUMBY

This type is used for determining how enumerated data will be returned when using the IEnumVariant interface returned via the _NewEnum method. The following constants are defined:

icENUM_NONSORTED: The data returned from the _NewEnum interface is returned in an implementation-derived sequence and therefore cannot be guaranteed to be in any order.

icENUM_ASCENDING_KEY: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the keys associated with each item.

icENUM_DESCENDING_KEY: The data returned from the _NewEnum interface is sorted in a descending sequence based on the keys associated with each item.

icENUM_ASCENDING_ACCESS_TIME: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the access time of each item.

icENUM_DESCENDING_ACCESS_TIME: The data returned from the _NewEnum interface is sorted in a descending sequence based on the access time of each item.

icENUM_ASCENDING_INDEX: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the keys associated with each item. This data is simply the index number into the array.

icENUM_DESCENDING_INDEX: The data returned from the _NewEnum interface is sorted in a descending sequence based on the keys associated with each item. This data is simply the index number into the array.

icENUM_ASCENDING_HITCOUNT: The data returned from the _NewEnum interface is sorted in an ascending sequence based on the hit counts for an item.

icENUM_DESCENDING_HITCOUNT: The data returned from the _NewEnum interface is sorted in a descending sequence based on the hit counts for an item.

ENUMTYPES

This type is used for determining what type of data, whether key or value, will be returned when using the IEnumVariant interface returned via the _NewEnum method. The following constants are defined:

icENUM_VALUE: The data returned from the _NewEnum interface is the value or data that was stored with the Add method.

icENUM_KEY: The data returned from the _NewEnum interface is the key that was stored with the Add method.

icENUM_HITCOUNT: The data returned from the _NewEnum interface is the hit count for the specified item.

SORTON

This type is used for determining what data is used to sort the general index.

icSORT_TIME: Sort based on the access time associated with an item.

icSORT_KEY: Sort based on the key associated with an item.

icSORT_HITCOUNT: Sort based on the hit count associated with an item.

Events

ItemAdded

Fired when an item is added to the cache.

Visual Basic event syntax

Private Sub object_ItemAdded(ByVal NewItemIndex As Long)

Parameters

NewItemIndex: Index of item just added.

Remarks

This event is fired after the item has been added to the cache.

CacheFlushing

Fired when the cache is about to be flushed.

Visual Basic event syntax

Private Sub object_CacheFlushing()

CacheFlushed

Fired when the cache has finished flushing.

Visual Basic event syntax

Private Sub object_CacheFlushed()

CacheExtending

Fired when the cache is about to be extended.

Visual Basic event syntax

Private Sub object_CacheExtending()

CacheExtended

Fired when the cache has finished extending.

Visual Basic event syntax

Private Sub object_CacheExtended()

CacheClearing

Fired when the cache is about to be cleared.

Visual Basic event syntax

Private Sub object_CacheClearing()

CacheCleared

Fired when the cache has finished clearing.

Visual Basic event syntax

Private Sub object_CacheCleared()

CacheSorting

Fired when the cache is about to be sorted.

Visual Basic event syntax

Private Sub object_CacheSorting()

CacheSorted

Fired when the cache has finished sorting.

Visual Basic event syntax

Private Sub object_CacheSorted()

Comments? We welcome your feedback at duwamish@microsoft.com.