# Module: `gears.cache`

Cache object with data that can be garbage-collected.

Here is an example with a basic cache:

**Usage example output**:

new entry created with value 0 0 new entry created with value 1 42 new entry created with value 2 84 0

### Usage:

-      local test_cache = cache.new(function(test)
           -- let's just print about what we created
           print("new entry created with value " .. test)
           -- Pretend this is some expensive computation
           return test * 42
       end)
       -- Populate the cache
       print(test_cache:get(0))
       print(test_cache:get(1))
       print(test_cache:get(2))
       -- no message since it exists
       print(test_cache:get(0))

       The example below demonstrates how the garbage collector will clear the
       cache:

      **Usage example output**:

          cache object #0 for first
          cache object #1 for second
          cache object #0 for first
          forcing a garbage collect
          cache object #2 for first
          cache object #3 for second

-     local function tostring_for_cache(obj)
          return obj[1]
      end
      local counter = 0
      local wrapper_cache = gears.cache.new(function(arg)
          local kind = "cache object #" .. tostring(counter) .. " for " .. tostring(arg)
          counter = counter + 1
          return setmetatable({ kind }, { __tostring = tostring_for_cache })
      end)
      print(wrapper_cache:get("first"))
      print(wrapper_cache:get("second"))
      -- No new object since it already exists
      print(wrapper_cache:get("first"))
      print("forcing a garbage collect")
      -- The GC can *always* clear the cache
      collectgarbage("collect")
      print(wrapper_cache:get("first"))
      print(wrapper_cache:get("second"))

### Info:

- Copyright: 2015 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Constructors

gears.cache (creation_cb) | Create a new cache object. |

## Methods

:get (...) | Get an entry from the cache, creating it if it's missing. |

## Constructors

🔗 gears.cache (creation_cb)
  Create a new cache object. A cache keeps some data that can be garbage-collected at any time, but might be useful to keep.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  creation_cb |  |  | Callback that is used for creating missing cache entries.

  ### Returns:

  A new cache object.

## Methods

🔗 :get (...)
  Get an entry from the cache, creating it if it's missing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  ... |  |  | Arguments for the creation callback. These are checked against the cache contents for equality.

  ### Returns:

  The entry from the cache

generated by LDoc 1.5.0