/ 
AmberDB-5.22.0
/ AmberDB::Cache

NAME

AmberDB::Cache - Native .db and .inx RAM-Disk (tmpfs) unified cache and persistent staging buffer engine

SYNOPSIS

# 1. Soft Cache (use_cache => 1):
# Custom caching for key-value datasets:
$adb->cache_write("catalog_product", "featured_items", @product_records);
my @records = $adb->cache_read("catalog_product", "featured_items");
$adb->cache_delete("catalog_product", "featured_items");

# 2. Hard Cache (use_cache => 2):
# Preloads entire database and index files into tmpfs RAM-disk:
$adb->cache_preload("catalog_category");

# 3. Persistent Disk Buffer Staging (stored in dbstore/buffer/):
$adb->buffer_write("export_job", @large_dataset_chunks);
my @staged_data = $adb->buffer_read("export_job");
$adb->buffer_delete("export_job");

# 4. RAM-Disk diagnostics and setup info:
my $info = $adb->cache_setup();

DESCRIPTION

AmberDB::Cache provides two complementary high-performance caching subsystems:

1. Unified RAM-Disk (tmpfs / ImDisk) Cache: Mirrors AmberDB's native .db (record data) and .inx (primary indexes) files in ultra-fast memory storage under dbstore/cache/. Supports TTL expiration (cache_ttl) and atomic background cache preloading.
2. Persistent Disk Buffer Staging: Manages temporary serialized staging tables under dbstore/buffer/ for multi-stage ETL pipelines, large dataset transformations, or batch background workers.

Inheritance Note: AmberDB inherits from AmberDB::Cache via use parent. All cache and buffer methods documented below can be invoked directly on any $adb instance.

METHODS

cache_setup()

Inspects operating system environment (Linux tmpfs or Windows ImDisk), returns diagnostic metadata, mount status, configured cache size, and paths to RAM-disk helper setup scripts (bash, powershell, perl).

my $diag = $adb->cache_setup();
# Returns: { is_mounted => 1, mount_desc => "tmpfs mounted on ...", cache_size => "512M", ... }

cache_read($tableid, $key, [$type])

Reads and deserializes a cached record from cache/$tableid.db (for record data) or cache/$tableid.inx (for metadata keys). Returns the decoded list of fields. Checks TTL expiration automatically.

my @cached_row = $adb->cache_read("catalog_product", "101");

cache_write($tableid, $key, @records)

Serializes and writes record data to the RAM-disk cache file.

$adb->cache_write("catalog_product", "top_sellers", [ 101, "Prod A" ], [ 102, "Prod B" ]);

cache_delete($tableid, [$key], [$type])

Invalidates cache entries. If $key is provided, removes only that specific key. If $key is omitted, removes and unlinks the entire table cache files (both .db and .inx).

$adb->cache_delete("catalog_product", "featured_items"); # Invalidate single entry
$adb->cache_delete("catalog_product");                  # Clear entire table cache

cache_preload($tableid)

Preloads all records and metadata from the persistent storage tables directory into the RAM-disk cache directory. Uses atomic temporary files (.tmp.$$) and file locking to prevent race conditions during live updates.

$adb->cache_preload("catalog_category");

cache_ensure($tableid)

Ensures that the RAM-disk cache for a table configured with use_cache => 2 is populated and valid. Automatically triggers cache_preload if the cache file is absent or expired.

my $cache_path = $adb->cache_ensure("catalog_category");

buffer_write($tableid, @records)

Writes structured records to a persistent disk buffer file located at dbstore/buffer/${tableid}.tmp. Uses atomic temp-file replacement for safe multi-process writes.

$adb->buffer_write("nightly_import", @processed_rows);

buffer_read($tableid)

Reads and deserializes all staged records from the disk buffer file. Returns a list of array references.

my @rows = $adb->buffer_read("nightly_import");

buffer_delete($tableid)

Deletes and unlinks the disk buffer staging file for the given table ID.

$adb->buffer_delete("nightly_import");

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2020-2026 Maruf Cetin.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.