SmartMap

The SmartMap class provides a simple way to cache the values of an arbitrary mapping function. This is useful when there is some expensive operation that is regularly performed on a specific set of values and caching the result gives a significant performance improvement. There is also a mechanism to invalidate the whole cache, as well as just specific keys.

Example

local MyModule = select(2, ...).MyModule
local SmartMap = MyModule:From("LibTSMUtil"):IncludeClassType("SmartMap")

local function LookupValue(key)
   -- Assume this is an expensive and non-trivial operation
   return strupper(key)
end

local map = SmartMap.New("string", "string", LookupValue)

local reader = map:CreateReader(function(_, pendingChanges)
   for key, prevValue in pairs(pendingChanges) do print("CHANGE", key, prevValue) end
end)
print(reader["a"]) -- A
print(reader["b"]) -- B

-- Invalidate the mapping for just one key
map:ValueChanged("a")
-- CHANGE   a   A

-- Invalidate the entire map if the underlying operation changes significantly
map:Invalidate()
-- CHANGE   b   B

Memory Management

Both SmartMap and SmartMapReader objects are intended to never be GC'd and have a static lifecycle (i.e. one that's equal to the lifecycle of the application).

API

Inherits: Class

Methods

CreateReader

function SmartMap:CreateReader(callback)
  -> SmartMapReader

Creates a new reader.

Parameters:

Name	Type	Description
callback	fun(reader: SmartMapReader<K, V>, pendingChanges: table)	The function to call when a value within the map changes

Returns:

Type	Description
SmartMapReader

GetKeyType

function SmartMap:GetKeyType()
  -> <K:"string" | "number">

Gets the type of the smart map's keys.

Returns:

Type	Description
<K:"string" | "number">

GetValueType

function SmartMap:GetValueType()
  -> <V:"string" | "number" | "boolean">

Gets the type of the smart map's values.

Returns:

Type	Description
<V:"string" | "number" | "boolean">

Invalidate

function SmartMap:Invalidate()

Invalidates all data in the smart map.

Iterator

function SmartMap:Iterator()
  -> fun():K, V, table

Iterates over all data in the smart map.

Returns:

Type	Description
fun():K, V	Iterator with fields: key, value
table

SetCallbacksPaused

function SmartMap:SetCallbacksPaused(paused)

Pausese or unpauses reader callbacks.

Parameters:

Name	Type	Description
paused	boolean	Whether or not callbacks are paused

ValueChanged

function SmartMap:ValueChanged(key)

Called when the value has changed for a given key to fetch the new one and notify the readers.

Parameters:

Name	Type	Description
key	K	The key which changed

_Get

function SmartMap:_Get(key)

Parameters:

Name	Type	Description
key	``

__init

function SmartMap:__init(keyType, valueType, lookupFunc)

Parameters:

Name	Type	Description
keyType	<K>
valueType	<V>
lookupFunc	fun(key: K): V	A function which looks up the value for a specific key

Functions

New

function SmartMap.New(keyType, valueType, lookupFunc)
  -> SmartMap

Create a new smart map object.

Parameters:

Name	Type	Description
keyType	<K>	The type of the keys
valueType	<V>	The type of the values
lookupFunc	fun(key: K): V	A function which looks up the value for a specific key

Returns:

Type	Description
SmartMap