From b9bb9cbe69ee123d6e91c3edb66bd34409674f8b Mon Sep 17 00:00:00 2001 From: Seth Barberee Date: Fri, 3 Jan 2020 06:42:39 -0600 Subject: [PATCH] add docs for gears.cache --- lib/gears/cache.lua | 12 +++++++++++ .../text/gears/cache/another_cache.lua | 21 +++++++++++++++++++ .../text/gears/cache/another_cache.output.txt | 6 ++++++ tests/examples/text/gears/cache/cache.lua | 14 +++++++++++++ .../text/gears/cache/cache.output.txt | 7 +++++++ 5 files changed, 60 insertions(+) create mode 100644 tests/examples/text/gears/cache/another_cache.lua create mode 100644 tests/examples/text/gears/cache/another_cache.output.txt create mode 100644 tests/examples/text/gears/cache/cache.lua create mode 100644 tests/examples/text/gears/cache/cache.output.txt diff --git a/lib/gears/cache.lua b/lib/gears/cache.lua index 9fb1d908b..1be1d8f4a 100644 --- a/lib/gears/cache.lua +++ b/lib/gears/cache.lua @@ -1,4 +1,16 @@ --------------------------------------------------------------------------- +--- Cache object with data that can be garbage-collected. +-- +-- Here is an example with a basic cache: +-- +--@DOC_text_gears_cache_cache_EXAMPLE@ +-- +-- The example below demonstrates how the garbage collector will clear the +-- cache: +-- +--@DOC_text_gears_cache_another_cache_EXAMPLE@ +-- +-- -- @author Uli Schlachter -- @copyright 2015 Uli Schlachter -- @classmod gears.cache diff --git a/tests/examples/text/gears/cache/another_cache.lua b/tests/examples/text/gears/cache/another_cache.lua new file mode 100644 index 000000000..db260fe2d --- /dev/null +++ b/tests/examples/text/gears/cache/another_cache.lua @@ -0,0 +1,21 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +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")) diff --git a/tests/examples/text/gears/cache/another_cache.output.txt b/tests/examples/text/gears/cache/another_cache.output.txt new file mode 100644 index 000000000..d932c681c --- /dev/null +++ b/tests/examples/text/gears/cache/another_cache.output.txt @@ -0,0 +1,6 @@ +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 diff --git a/tests/examples/text/gears/cache/cache.lua b/tests/examples/text/gears/cache/cache.lua new file mode 100644 index 000000000..d5326f52b --- /dev/null +++ b/tests/examples/text/gears/cache/cache.lua @@ -0,0 +1,14 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local cache = require("gears.cache") --DOC_HIDE +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)) diff --git a/tests/examples/text/gears/cache/cache.output.txt b/tests/examples/text/gears/cache/cache.output.txt new file mode 100644 index 000000000..873bc078b --- /dev/null +++ b/tests/examples/text/gears/cache/cache.output.txt @@ -0,0 +1,7 @@ +new entry created with value 0 +0 +new entry created with value 1 +42 +new entry created with value 2 +84 +0