cache manager

Vala cache library with a shared cache API and multiple storage backends.

Contents

• Overview
• Implemented Backends
• Core API
• Quick Usage
• Build
• Test
• Release artifacts
• Use generated library in other projects
• Install via Vamposer
• Dependencies
• License

Overview

This project provides:

• common cache interface (CacheInterface)
• common cache item interface (CacheItemInterface)
• in-memory backend
• filesystem backend with persisted items

TTL constants are available in the ValaTux.CacheManager namespace:

• DEFAULT_TTL
• TTL_MINUTE, TTL_HOUR, TTL_DAY, TTL_WEEK, TTL_MONTH, TTL_YEAR
• TTL_INFINITE

Implemented Backends

Memory backend

Namespace: ValaTux.CacheManager.Memory

• stores items in RAM
• no serialization required
• supports save, getItem, getItems, hasItem, delete operations, and clear

Filesystem backend

Namespace: ValaTux.CacheManager.Filesystem

• stores items as .cache files in a cache directory
• uses hashed key names for file paths
• supports persistence across process restarts
• supports JSON payloads via GLib.Value with Json.Node

Supported filesystem value types:

• string
• int, int64
• uint, uint64
• bool
• double
• Json.Node

Core API

Cache:

• CacheItemInterface? getItem (string key)
• CacheItemInterface[] getItems (string[] keys)
• bool hasItem (string key)
• bool clear ()
• bool deleteItem (string key)
• bool deleteItems (string[] keys)
• bool save (CacheItemInterface item)
• bool saveItems (CacheItemInterface[] items)
• bool saveDeferred (CacheItemInterface item)
• bool commit ()

Cache item:

• string getKey ()
• Value? getValue ()
• bool IsHit ()
• CacheItemInterface setValue (Value? value, int ttl = 0)
• CacheItemInterface expireAfter (int ttl)
• CacheItemInterface expireAt (int timestamp)

Quick Usage

Memory cache

using GLib;
using ValaTux.CacheManager;

var cache = new ValaTux.CacheManager.Memory.Cache ();
var item = new ValaTux.CacheManager.Memory.CacheItem ("user:1");

Value value = Value (typeof (string));
value.set_string ("alice");

item.setValue (value, (int) TTL_MINUTE);
cache.save (item);

CacheItemInterface? loaded = cache.getItem ("user:1");
if (loaded != null && loaded.IsHit ()) {
	Value? loaded_value = loaded.getValue ();
	stdout.printf ("%s\n", loaded_value.get_string ());
}

Filesystem cache with JSON value

using GLib;
using Json;
using ValaTux.CacheManager;

var cache = new ValaTux.CacheManager.Filesystem.Cache ();
var item = new ValaTux.CacheManager.Filesystem.CacheItem ("profile");

var parser = new Json.Parser ();
parser.load_from_data ("{\"name\":\"alice\",\"age\":30}", -1);

Value value = Value (typeof (Json.Node));
value.set_boxed (parser.get_root ().copy ());

item.setValue (value, (int) TTL_HOUR);
cache.save (item);

Build

meson setup builddir
meson compile -C builddir

Test

meson test -C builddir

or via Makefile helper:

make tests

Release artifacts

Tag-based release workflow (v*) publishes:

• shared library (lib*.so*)
• generated VAPI (src/vapi/*.vapi)
• generated header (src/*.h)
• bundled ZIP (<repo-name>-<tag>-linux.zip)

Use generated library in other projects

Option 1: Meson subproject dependency

In consumer project root:

./init.sh

Or run directly from GitHub:

curl -sSfL https://raw.githubusercontent.com/ValaTux/cache-manager/master/init.sh -o init.sh && chmod +x init.sh && ./init.sh && rm init.sh

Option 2: Local vapi/lib/include integration

In consumer project root:

curl -sSfL https://raw.githubusercontent.com/ValaTux/cache-manager/master/init-local-vapi.sh | bash

This helper downloads release artifacts (or builds from source) and prepares local vapi/, lib/, and include/ folders plus reusable Meson variables.

Install via Vamposer

In your consumer project root:

vamposer require ValaTux/cache-manager master
vamposer install

Then include generated Vamposer dependencies in your meson.build:

subdir('vamposer')

executable('my-app',
	sources,
	dependencies: [
		vamposer_deps
	]
)

You can also use a fixed tag or commit instead of master.

If you also want the test workspace, install it as a development dependency:

vamposer require --dev ValaTux/testcases master
vamposer install --dev

Dependencies

• glib-2.0
• gio-2.0
• gee-0.8
• json-glib-1.0
• vala_testcases (tests only)

License

MIT (see LICENSE).