{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# CacheStack\n",
    "\n",
    "A `CacheStack` allows combining multiple caches into a single prioritized hierarchy.\n",
    "It is a common pattern to combine a fast, local cache (like an in-memory cache) with a larger, slower, and potentially remote cache (like a database or file system).\n",
    "\n",
    "## Automatic Hit Transfer\n",
    "\n",
    "Whenever a hit is found in a higher-level cache, it is automatically transferred to the base cache (index 0). This ensures that frequently accessed data migrates to the fastest cache in your stack."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-22T19:56:31.302104Z",
     "iopub.status.busy": "2026-03-22T19:56:31.301859Z",
     "iopub.status.idle": "2026-03-22T19:56:32.048761Z",
     "shell.execute_reply": "2026-03-22T19:56:32.047930Z"
    }
   },
   "outputs": [],
   "source": "import tempfile\nimport os\nfrom fleche import fleche, cache\nfrom fleche.caches import Cache, CacheStack\nfrom fleche.storage import ValueMemory, CallMemory, ValuePickleFile, CallPickleFile\nfrom fleche.storage.sql import Sql\n\n# 1. Setup a 'remote' persistent cache\ntmp_dir = tempfile.TemporaryDirectory()\n# Use PickleFile for values and Sql for calls to simulate a robust remote storage\nremote_storage_values = ValuePickleFile.with_cloudpickle(tmp_dir.name)\nremote_storage_calls = Sql(f\"sqlite:///{os.path.join(tmp_dir.name, 'cache.db')}\")\nremote_cache = Cache(remote_storage_values, remote_storage_calls)\n\n# 2. Setup a 'local' fast memory cache\nlocal_cache = Cache(ValueMemory({}), CallMemory({}))\n\n@fleche\ndef expensive_computation(x):\n    print(f\"Computing {x}...\")\n    return x * 10\n\n# Pre-populate the remote cache\nwith cache(remote_cache):\n    expensive_computation(42)\n\nprint(\"Remote cache contains 42:\", remote_cache.contains(expensive_computation.digest(42)))\nprint(\"Local cache contains 42: \", local_cache.contains(expensive_computation.digest(42)))"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating the stack\n",
    "We prioritize `local_cache` over `remote_cache` by putting it at the front of the stack."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-22T19:56:32.050884Z",
     "iopub.status.busy": "2026-03-22T19:56:32.050559Z",
     "iopub.status.idle": "2026-03-22T19:56:32.059333Z",
     "shell.execute_reply": "2026-03-22T19:56:32.058544Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calling expensive_computation(42) via stack...\n",
      "Result: 420\n",
      "Local cache now contains 42: True\n"
     ]
    }
   ],
   "source": [
    "stack = CacheStack((local_cache, remote_cache))\n",
    "\n",
    "with cache(stack):\n",
    "    # Loading 42 will hit remote_cache and automatically transfer it to local_cache\n",
    "    print(\"Calling expensive_computation(42) via stack...\")\n",
    "    result = expensive_computation(42)\n",
    "    print(f\"Result: {result}\")\n",
    "\n",
    "print(\"Local cache now contains 42:\", local_cache.contains(expensive_computation.digest(42)))\n",
    "\n",
    "# Cleanup\n",
    "tmp_dir.cleanup()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}