analytics/Plausible.Cache.html
2024-04-29 06:06:16 +00:00

507 lines
18 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.31.1">
<meta name="project" content="Plausible v0.0.1">
<title>Plausible.Cache — Plausible v0.0.1</title>
<link rel="stylesheet" href="dist/html-elixir-FM2CSD74.css" />
<script src="dist/handlebars.runtime-NWIB6V2M.js"></script>
<script src="dist/handlebars.templates-43PMFBC7.js"></script>
<script src="dist/sidebar_items-F36A4795.js"></script>
<script src="docs_config.js"></script>
<script async src="dist/html-L4O5OK2K.js"></script>
</head>
<body data-type="modules" class="page-behaviour">
<script>
try {
var settings = JSON.parse(localStorage.getItem('ex_doc:settings') || '{}');
if (settings.theme === 'dark' ||
((settings.theme === 'system' || settings.theme == null) &&
window.matchMedia('(prefers-color-scheme: dark)').matches)
) {
document.body.classList.add('dark')
}
} catch (error) { }
</script>
<div class="main">
<button id="sidebar-menu" class="sidebar-button sidebar-toggle" aria-label="toggle sidebar" aria-controls="sidebar">
<i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>
<div class="background-layer"></div>
<nav id="sidebar" class="sidebar">
<div class="sidebar-header">
<div class="sidebar-projectInfo">
<a href="readme.html" class="sidebar-projectImage">
<img src="assets/logo.png" alt="Plausible" />
</a>
<div>
<a href="readme.html" class="sidebar-projectName" translate="no">
Plausible
</a>
<div class="sidebar-projectVersion" translate="no">
v0.0.1
</div>
</div>
</div>
<ul id="sidebar-listNav" class="sidebar-listNav" role="tablist">
<li>
<button id="extras-list-tab-button" role="tab" data-type="extras" aria-controls="extras-tab-panel" aria-selected="true" tabindex="0">
Pages
</button>
</li>
<li>
<button id="modules-list-tab-button" role="tab" data-type="modules" aria-controls="modules-tab-panel" aria-selected="false" tabindex="-1">
Modules
</button>
</li>
<li>
<button id="tasks-list-tab-button" role="tab" data-type="tasks" aria-controls="tasks-tab-panel" aria-selected="false" tabindex="-1">
<span translate="no">Mix</span> Tasks
</button>
</li>
</ul>
</div>
<div id="extras-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="extras-list-tab-button">
<ul id="extras-full-list" class="full-list"></ul>
</div>
<div id="modules-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="modules-list-tab-button" hidden>
<ul id="modules-full-list" class="full-list"></ul>
</div>
<div id="tasks-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="tasks-list-tab-button" hidden>
<ul id="tasks-full-list" class="full-list"></ul>
</div>
</nav>
<main class="content">
<output role="status" id="toast"></output>
<div class="content-outer">
<div id="content" class="content-inner">
<div class="top-search">
<div class="search-settings">
<form class="search-bar" action="search.html">
<label class="search-label">
<span class="sr-only">Search documentation of Plausible</span>
<input name="q" type="text" class="search-input" placeholder="Search Documentation (press /)" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
</label>
<button type="submit" class="search-button" aria-label="Submit Search">
<i class="ri-search-2-line ri-lg" aria-hidden="true" title="Submit search"></i>
</button>
<button type="button" tabindex="-1" class="search-close-button" aria-hidden="true">
<i class="ri-close-line ri-lg" title="Cancel search"></i>
</button>
</form>
<div class="autocomplete">
</div>
<button class="icon-settings display-settings">
<i class="ri-settings-3-line"></i>
<span class="sr-only">Settings</span>
</button>
</div>
</div>
<h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L1" title="View Source" class="icon-action" rel="help">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
<span translate="no">Plausible.Cache</span> <small>behaviour</small>
<small class="app-vsn" translate="no">(Plausible v0.0.1)</small>
</h1>
<section id="moduledoc">
<p>Caching interface specific for Plausible. Usage:</p><pre><code class="makeup elixir" translate="no"><span class="kn">use</span><span class="w"> </span><span class="nc">Plausible.Cache</span><span class="w">
</span><span class="c1"># - Implement the callbacks required</span><span class="w">
</span><span class="c1"># - Optionally override `unwrap_cache_keys/1`</span><span class="w">
</span><span class="c1"># - Populate the cache with `Plausible.Cache.Warmer`</span></code></pre><p>Serves as a wrapper around <a href="Plausible.Cache.Adapter.html"><code class="inline">Plausible.Cache.Adapter</code></a>, where the underlying
implementation can be transparently swapped.</p><p>Even though normally the relevant Adapter processes are started, cache access is disabled
during tests via the <code class="inline">:plausible, Elixir.Plausible.Cache, enabled: bool()</code> application env key.
This can be overridden on case by case basis, using the child specs options.</p><p>The <code class="inline">base_db_query/0</code> callback is used to generate the base query that is
executed on every cache refresh. </p><p>There are two modes of refresh operation: <code class="inline">:all</code> and <code class="inline">:updated_recently</code>;
the former will invoke the query as is and clear all the existing entries,
while the latter will attempt to limit the query to only the records that
have been updated in the last 15 minutes and try to merge the new results with
existing cache entries.</p><p>Both refresh modes are normally executed periodically from within a warmer process;
see: <a href="Plausible.Cache.Warmer.html"><code class="inline">Plausible.Cache.Warmer</code></a>. The reason for two modes is that the latter is lighter
on the database and can be executed more frequently.</p><p>When Cache is disabled via application env, the <code class="inline">get/1</code> function
falls back to pure database lookups (implemented via <code class="inline">get_from_source/1</code> callback.
This should help with introducing cached lookups in existing code,
so that no existing tests should break.</p><p>Refreshing the cache emits telemetry event defined as per <code class="inline">telemetry_event_refresh/2</code>.</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Summary</span>
</h1>
<div class="summary-callbacks summary">
<h2>
<a href="#callbacks">Callbacks</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:base_db_query/0" translate="no">base_db_query()</a>
</div>
<div class="summary-synopsis"><p>Returns the base Ecto query used to refresh the cache</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:child_id/0" translate="no">child_id()</a>
</div>
<div class="summary-synopsis"><p>Supervisor child id, must be unique within the supervision tree</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:count_all/0" translate="no">count_all()</a>
</div>
<div class="summary-synopsis"><p>Counts all items at the source, an aggregate query most likely</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:get_from_source/1" translate="no">get_from_source(any)</a>
</div>
<div class="summary-synopsis"><p>Retrieves the item from the source, in case the cache is disabled</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:name/0" translate="no">name()</a>
</div>
<div class="summary-synopsis"><p>Unique cache name, used by underlying implementation</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:unwrap_cache_keys/1" translate="no">unwrap_cache_keys(list)</a>
</div>
<div class="summary-synopsis"><p>Optionally unwraps the keys of the cache items, in case one item is stored under multiple keys</p></div>
</div>
</div>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#enabled?/0" translate="no">enabled?()</a>
</div>
<div class="summary-synopsis"><p>Looks for application env value at <code class="inline">:plausible, Elixir.Plausible.Cache, enabled: bool()</code></p></div>
</div>
</div>
</section>
<section id="callbacks" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#callbacks">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Callbacks</span>
</h1>
<div class="callbacks-list">
<section class="detail" id="c:base_db_query/0">
<div class="detail-header">
<a href="#c:base_db_query/0" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">base_db_query()</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L47" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> base_db_query() :: <a href="https://hexdocs.pm/ecto/3.11.1/Ecto.Query.html#t:t/0">Ecto.Query.t</a>()</pre>
</div>
<p>Returns the base Ecto query used to refresh the cache</p>
</section>
</section>
<section class="detail" id="c:child_id/0">
<div class="detail-header">
<a href="#c:child_id/0" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">child_id()</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L41" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> child_id() :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()</pre>
</div>
<p>Supervisor child id, must be unique within the supervision tree</p>
</section>
</section>
<section class="detail" id="c:count_all/0">
<div class="detail-header">
<a href="#c:count_all/0" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">count_all()</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L43" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> count_all() :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">integer</a>()</pre>
</div>
<p>Counts all items at the source, an aggregate query most likely</p>
</section>
</section>
<section class="detail" id="c:get_from_source/1">
<div class="detail-header">
<a href="#c:get_from_source/1" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">get_from_source(any)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L49" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> get_from_source(<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()</pre>
</div>
<p>Retrieves the item from the source, in case the cache is disabled</p>
</section>
</section>
<section class="detail" id="c:name/0">
<div class="detail-header">
<a href="#c:name/0" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">name()</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L39" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> name() :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()</pre>
</div>
<p>Unique cache name, used by underlying implementation</p>
</section>
</section>
<section class="detail" id="c:unwrap_cache_keys/1">
<div class="detail-header">
<a href="#c:unwrap_cache_keys/1" class="detail-link" title="Link to this callback">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this callback</span>
</a>
<h1 class="signature" translate="no">unwrap_cache_keys(list)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L45" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<div class="specs">
<pre translate="no"><span class="attribute">@callback</span> unwrap_cache_keys([<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()]) :: [{<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()}]</pre>
</div>
<p>Optionally unwraps the keys of the cache items, in case one item is stored under multiple keys</p>
</section>
</section>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Functions</span>
</h1>
<div class="functions-list">
<section class="detail" id="enabled?/0">
<div class="detail-header">
<a href="#enabled?/0" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">enabled?()</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible/cache.ex#L52" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Looks for application env value at <code class="inline">:plausible, Elixir.Plausible.Cache, enabled: bool()</code></p>
</section>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
<button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
Search HexDocs
</button>
<a href="Plausible.epub" title="ePub version">
Download ePub version
</a>
</span>
</p>
<p class="built-using">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.31.1) for the
<a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>
</p>
</footer>
</div>
</div>
</main>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad: true})</script>
</body>
</html>