feat(cache): add usage examples for cache module

GaspardKirira · GaspardKirira · commit 69d48af9c472 · 2026-03-31T11:39:06.000+03:00
diff --git a/examples/01_memory_cache_basic.cpp b/examples/01_memory_cache_basic.cpp
@@ -0,0 +1,71 @@
+/**
+ *
+ *  @file 01_memory_cache_basic.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+// Run:
+//   vix run examples/cache/01_memory_cache_basic.cpp
+
+#include <chrono>
+#include <iostream>
+#include <memory>
+
+#include <vix/cache/Cache.hpp>
+#include <vix/cache/CacheContext.hpp>
+#include <vix/cache/CacheEntry.hpp>
+#include <vix/cache/CachePolicy.hpp>
+#include <vix/cache/MemoryStore.hpp>
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(
+             steady_clock::now().time_since_epoch())
+      .count();
+}
+
+int main()
+{
+  using namespace vix::cache;
+
+  auto store = std::make_shared<MemoryStore>();
+
+  CachePolicy policy;
+  policy.ttl_ms = 5'000;
+
+  Cache cache(policy, store);
+
+  const std::string key = "GET /api/users?page=1";
+  const auto t0 = now_ms();
+
+  CacheEntry entry;
+  entry.status = 200;
+  entry.body = R"({"users":[1,2,3]})";
+  entry.headers["Content-Type"] = "application/json";
+  entry.created_at_ms = t0;
+
+  cache.put(key, entry);
+
+  auto cached = cache.get(key, t0 + 100, CacheContext::Online());
+
+  if (!cached)
+  {
+    std::cout << "cache miss\n";
+    return 1;
+  }
+
+  std::cout << "cache hit\n";
+  std::cout << "status: " << cached->status << "\n";
+  std::cout << "body  : " << cached->body << "\n";
+  return 0;
+}
diff --git a/examples/02_file_cache_persistence.cpp b/examples/02_file_cache_persistence.cpp
@@ -0,0 +1,91 @@
+/**
+ *
+ *  @file 02_file_cache_persistence.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+// Run:
+//   vix run examples/cache/02_file_cache_persistence.cpp
+
+#include <chrono>
+#include <filesystem>
+#include <iostream>
+#include <memory>
+
+#include <vix/cache/Cache.hpp>
+#include <vix/cache/CacheContext.hpp>
+#include <vix/cache/CacheEntry.hpp>
+#include <vix/cache/CachePolicy.hpp>
+#include <vix/cache/FileStore.hpp>
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<std::chrono::milliseconds>(
+             std::chrono::steady_clock::now().time_since_epoch())
+      .count();
+}
+
+int main()
+{
+  using namespace vix::cache;
+
+  const std::filesystem::path file = "./build/examples/cache/cache_http.json";
+
+  {
+    auto store = std::make_shared<FileStore>(FileStore::Config{
+        .file_path = file,
+        .pretty_json = true});
+
+    CachePolicy policy;
+    policy.ttl_ms = 10'000;
+
+    Cache cache(policy, store);
+
+    CacheEntry entry;
+    entry.status = 200;
+    entry.body = R"({"source":"disk"})";
+    entry.headers["Content-Type"] = "application/json";
+    entry.created_at_ms = now_ms();
+
+    cache.put("GET /api/products?limit=3", entry);
+
+    std::cout << "entry written to disk\n";
+  }
+
+  {
+    auto store = std::make_shared<FileStore>(FileStore::Config{
+        .file_path = file,
+        .pretty_json = false});
+
+    CachePolicy policy;
+    policy.ttl_ms = 10'000;
+
+    Cache cache(policy, store);
+
+    auto cached = cache.get(
+        "GET /api/products?limit=3",
+        now_ms() + 100,
+        CacheContext::Online());
+
+    if (!cached)
+    {
+      std::cout << "cache miss after reload\n";
+      return 1;
+    }
+
+    std::cout << "cache hit after reload\n";
+    std::cout << "body: " << cached->body << "\n";
+  }
+
+  return 0;
+}
diff --git a/examples/03_lru_cache_eviction.cpp b/examples/03_lru_cache_eviction.cpp
@@ -0,0 +1,79 @@
+/**
+ *
+ *  @file 03_lru_cache_eviction.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+// Run:
+//   vix run examples/cache/03_lru_cache_eviction.cpp
+
+#include <chrono>
+#include <iostream>
+#include <memory>
+
+#include <vix/cache/Cache.hpp>
+#include <vix/cache/CacheContext.hpp>
+#include <vix/cache/CacheEntry.hpp>
+#include <vix/cache/CachePolicy.hpp>
+#include <vix/cache/LruMemoryStore.hpp>
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(
+             steady_clock::now().time_since_epoch())
+      .count();
+}
+
+static vix::cache::CacheEntry make_entry(
+    const std::string &body,
+    std::int64_t t)
+{
+  vix::cache::CacheEntry e;
+  e.status = 200;
+  e.body = body;
+  e.created_at_ms = t;
+  return e;
+}
+
+int main()
+{
+  using namespace vix::cache;
+
+  auto store = std::make_shared<LruMemoryStore>(
+      LruMemoryStore::Config{.max_entries = 2});
+
+  CachePolicy policy;
+  policy.ttl_ms = 10'000;
+
+  Cache cache(policy, store);
+
+  const auto t0 = now_ms();
+
+  cache.put("k1", make_entry("A", t0));
+  cache.put("k2", make_entry("B", t0));
+
+  // Touch k1 -> k2 becomes least recently used
+  (void)cache.get("k1", t0 + 1, CacheContext::Online());
+
+  cache.put("k3", make_entry("C", t0 + 2));
+
+  auto k1 = cache.get("k1", t0 + 3, CacheContext::Online());
+  auto k2 = cache.get("k2", t0 + 3, CacheContext::Online());
+  auto k3 = cache.get("k3", t0 + 3, CacheContext::Online());
+
+  std::cout << "k1: " << (k1 ? "present" : "missing") << "\n";
+  std::cout << "k2: " << (k2 ? "present" : "missing") << "\n";
+  std::cout << "k3: " << (k3 ? "present" : "missing") << "\n";
+
+  return 0;
+}
diff --git a/examples/04_offline_and_network_error.cpp b/examples/04_offline_and_network_error.cpp
@@ -0,0 +1,82 @@
+/**
+ *
+ *  @file 04_offline_and_network_error.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+// Run:
+//   vix run examples/cache/04_offline_and_network_error.cpp
+
+#include <chrono>
+#include <iostream>
+#include <memory>
+
+#include <vix/cache/Cache.hpp>
+#include <vix/cache/CacheContext.hpp>
+#include <vix/cache/CacheEntry.hpp>
+#include <vix/cache/CachePolicy.hpp>
+#include <vix/cache/MemoryStore.hpp>
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(
+             steady_clock::now().time_since_epoch())
+      .count();
+}
+
+int main()
+{
+  using namespace vix::cache;
+
+  auto store = std::make_shared<MemoryStore>();
+
+  CachePolicy policy;
+  policy.ttl_ms = 100;
+  policy.allow_stale_if_offline = true;
+  policy.stale_if_offline_ms = 10'000;
+  policy.allow_stale_if_error = true;
+  policy.stale_if_error_ms = 5'000;
+
+  Cache cache(policy, store);
+
+  const auto t0 = now_ms();
+
+  CacheEntry entry;
+  entry.status = 200;
+  entry.body = R"({"cached":true})";
+  entry.created_at_ms = t0;
+
+  cache.put("GET /api/profile", entry);
+
+  {
+    auto fresh = cache.get("GET /api/profile", t0 + 50, CacheContext::Online());
+    std::cout << "fresh online: " << (fresh ? "hit" : "miss") << "\n";
+  }
+
+  {
+    auto offline_stale = cache.get("GET /api/profile", t0 + 3000, CacheContext::Offline());
+    std::cout << "offline stale: " << (offline_stale ? "hit" : "miss") << "\n";
+  }
+
+  {
+    auto error_stale = cache.get("GET /api/profile", t0 + 4000, CacheContext::NetworkError());
+    std::cout << "network error stale: " << (error_stale ? "hit" : "miss") << "\n";
+  }
+
+  {
+    auto too_old = cache.get("GET /api/profile", t0 + 20'000, CacheContext::Offline());
+    std::cout << "too old offline: " << (too_old ? "hit" : "miss") << "\n";
+  }
+
+  return 0;
+}
diff --git a/examples/05_cache_key_and_headers.cpp b/examples/05_cache_key_and_headers.cpp
