Cache Library

From SolarStrike wiki
Revision as of 12:42, 8 September 2016 by Elverion (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Creating a cache instance

object Cache()

object Cache(string driver)

object Cache(string driver, table config)

The cache library is optional and the module must be required before use. Next, the cache class must be instantiated:

require('cache/cache');

cache = Cache();

You may optionally specify which driver you want to use and a table of configuration options (see driver details for more info).

Drivers

Various drivers may be used which determine how cached data will be handled. Each driver may have its own set of pros and cons. For instance the 'memory' driver should give great speed, but may consume a lot of memory, will not be saved to disk (the data disappears once the script terminates), and will not share data between instances. By default, the DB driver is used.


DB Driver

This will use SQLite internally to handle data. It should give good speed, but the primary benefit is that it will continually save to disk and all data will be shared across multiple instances. Using this driver will result in data being saved to 'cache.db' in the executing script's directory. You can explicitly create an instance of the DB driver by instantiating with the 'db' driver name:

cache = Cache('db');
-- OR: --
local settings = {
  file = 'mycachefile.db',
  table = 'cachetable',
};
cache = Cache('db', settings);


Optional configurations:

file The filename (and optionally path) of the file to use for storing the database; by default this is 'cache.db'
table The name of the table to use for storing cache data; by default this is 'cache'

Memory Driver

This will store cached data directly into the Lua engine's memory space. Speed should be great, but storing lots of cached data will require more memory. Cached information should be considered volatile; any cached data will be immediately lost as soon as the script terminates. Additionally, multiple instances of your script will not share data between them. You can explicitly create an instance of the memory driver by instantiating with the 'memory' driver name:

cache = Cache('memory');


Example usage

require('cache/cache');

function macro.init()
  cache = Cache(); -- Use the default cache driver
end

function macro.main()
  -- Returns the existing value, or generates and returns a new one
  local value = cache:remember('testValue', 1, function() return string.random('alnum', 16) end);

  print("Cached value:", value);
end


Supported methods

Cache:driverName

string Cache:driverName()

Returns the 'name' of a driver for descriptive use only.


Cache:get

value Cache:get(string itemName, defaultValue)

Returns a value from the cache if the item exists and is not expired, otherwise returns defaultValue or nil. In most cases you will probably want to either grab a cached value or set and return a new value, and so it is recommended to use Cache:remember() instead.


Cache:has

boolean Cache:has(string itemName)

Returns true if an item exists and is not expired, otherwise returns false.


Cache:set

Cache:set(string itemName, value, minutes) Cache:set(string itemName, value)

Sets an item in the cache that will expire in the number of minutes denoted by 'minutes'. If 'minutes' is not given, a value of 1 is assumed. If the item should never expire, pass a negative number for 'minutes.'


Cache:remember

value Cache:remember(string itemName, number minutes, function callback)

If the item exists and is not expired, the cached value is returned. Otherwise, the callback function will be called (which should return the value you want to be set) and used as the item's new value which expires in 'minutes' from now; again a negative 'minutes' value indicates it should never expire (or use Cache:rememberForever()). If the callback is used to generate a new value, that value is the one returned by this function.


Cache:rememberForever

value Cache:rememberForever(string itemName, function callback)

Exactly like Cache:remember(), only the item is set to never expire.


cache:renew

Cache:renew(string itemName, number minutes)

Updates the expires_at timestamp for an item so that it will expire in 'minutes' from now. If 'minutes' is nil, the item is set to never expire.


Cache:forget

Cache:forget(string itemName)

Removes an item from the cache, regardless of whether it is still valid, expired, or set to never expire.


Cache:flush

Cache:flush()

Removes all items from the cache.