Cache Library
#Creating a cache instance cache Cache() cache Cache(string driver) cache 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. You may optionally specify which driver you want to use and a table of configuration options (see driver details for more info).

Example:
require 'cache/cache'; cache = Cache(); -- Create a cache with default settings (will use DB driver) -- or -- cache = Cache('memory'); -- Create a memory-based cache
 #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:

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

Optional configurations:

Configuration nameTypeDescription
file string The filename (and optionally path) of the file to use for storing the database; by default this is 'cache.db'
table string 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: Example:

cache = Cache('memory');

 #Example usage Example:
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 [variable type] Cache:get(string itemName) [variable type] Cache:get(string itemName, [variable type] defaultValue)

Returns a value from the cache if the item exists and is not expired, otherwise returns defaultValue or nil if defaultValue is not given. 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:set [variable type] Cache:set(string itemName, [variable type] value) [variable type] Cache:set(string itemName, [variable type] value, number minutes)

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:has boolean Cache:has(string itemName)

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

 #Cache:remember [variable type] 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.

Example:
function macro.init() cache = Cache(); end function macro.main() myValue = cache:remember('myValue', 5, function () return someFunction(); end); -- myValue is now set to whatever someFunction() returned, and is saved into the cache -- someFunction() will only be called once every ~5 minutes, not every time macro.main() is run. end
 #Cache:rememberForever [variable type] 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.

Page last updated at 2018-10-02 21:55:03

Copyright 2024