Class: Cache

H .util.Cache

new H.util.Cache (maxSize, opt_onDrop, opt_filter)

The cache represents an in-memory LRU-cache with a fixed size. Once the elements held in the cache reach the maximum permitted size, the cache drops the elements with the oldest retrieval time stamp to bring the size of the cached data within bounds. Data elements held in the cache are stored with their IDs and size to facilitate retrieval.

Name	Type	Description
`maxSize`	number	A value indicating the maximum size of the cache
`opt_onDrop`	function(string, ?, number)	optional A callback to be invoked when a data element is dropped from the cache
`opt_filter`	function	optional A function to filter data elements that are not to be cached

Throws:

The constructor throws an error if the 'maxSize' argument is not a positive number, the opt_onDrop argument was set but is not a function or if the opt_filter argument was set but is not a function.

Implements

H.util.ICache

Methods

add (id, data, size)boolean

This method adds a data element to the cache and marks it as most recently used. The data element must have an identifier that allows for retrieving the object at a later stage and a size which will count towards the cache's maximum size.

Name	Type	Description
`id`	*	The identifier of this data element, the value is converted to a string.
`data`	*	the actual data to be stored
`size`	number	The size of the data element

Throws:

Throws an error if the 'size' argument is not a positive number.

Returns:

Type	Description
boolean	A Boolean value indicating whether the data was successfully added (`true`)

deRegisterOnDrop (callback)

This method de-registers a callback that is called each time an entry is dropped from the cache.

Name	Type	Description
`callback`	function	The callback that is invoked for each removed entry

drop (id)

This method explicitly removes an element from the cache.

Name	Type	Description
`id`	*	the id of the item to drop

forEach (callback, opt_ctx, opt_matcher)

This method executes a callback function on each entry in the cache. If the optional match predicate is specified, the callback is executed only on those entries for which the predicate returns true.

Name	Type	Description
`callback`	function(string, ?, number)	The callback to be invoked for each entry
`opt_ctx`	Object	optional An optional context object to be used as `this` within the callback
`opt_matcher`	function	optional An optional match predicate to filter the entries on which the callback operates

get (id, opt_noUpdate)*

This method retrieves an element from the cache and marks it as 'most recently used'.

Name	Type	Description
`id`	string	The ID of the data element to be retrieved.
`opt_noUpdate`	boolean	optional An optional flag to indicate if the retrieved object should not be marked as 'most recently used' (`true`)

Returns:

Type	Description
*	The data corresponding to the ID or `undefined` if the data element is not in the cache

getCurrentSize ()number

This method retrieves the current size of this cache.

Returns:

Type	Description
number	A value indicating the current size of the cache

getMaxSize ()number

This method retrieves the maximum size of the cache.

Returns:

Type	Description
number	A value indicating the maximum size of the cache

registerOnDrop (onDrop)

This method registers a callback to be invoked for each entry dropped from the cache.

Name	Type	Description
`onDrop`	function(string, ?, number)	A callback to be invoked when a data element is dropped from the cache

Throws:

throws an error if the onDrop argument is not a function

removeAll (opt_matcher)

This method removes all data elements from the cache. The caller can provide an optional match predicate to narrow down the selection of data elements to be removed.

Name	Type	Description
`opt_matcher`	function	optional An optional function that receives data entry IDs, data and sizes and returns `true` or `false` to remove or leave an entry in the cache, respectively

setMaxSize (maxSize)H.util.Cache

This method sets the maximum size of the cache. If the existing contents of the cache exceed the new size, the least recently used data elements are dropped.

Name	Type	Description
`maxSize`	number	A value indicating the new maximum size of the cache

Returns:

Type	Description
H.util.Cache	An object representing the cache