cache::async(3tcl)

💖 cache::async — the async in-memory cache glow-up 💖

okay bestie, welcome to the cache::async page from the Tcllib manual (section 3tcl, In-memory caches). it's a whole vibe. let's get into it 🫶

---

✨ NAME ✨

cache::async — Asynchronous in-memory cache

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require cache::async ?0.3.2?

::cache::async objectName commandprefix ?options...?

objectName get key donecmdprefix

objectName set key value

objectName unset key

objectName exists key

objectName clear ?key?

---

🦋 DESCRIPTION 🦋

so this package hands you objects that cache data in memory, and they operate asynchronously when it comes to requests and responses. like, you ask, and the answer shows up whenever it shows up. main character scheduling, honestly. 💅

the objects are agnostic with regard to cache keys and values — they literally do not care what you're storing — and any method they don't recognise gets delegated to the provider of cached data. those two properties together? it's giving facade. it makes it super easy to use caches as a facade for any data provider. no cap.

---

👑 API 👑

the package exports one class, cache::async, and here's the tea on it:

💫 ::cache::async objectName commandprefix ?options...?

this command creates a brand new cache object, and it comes with an associated global Tcl command whose name is objectName. you use that command to invoke all the various operations on the object. slay.

the commandprefix is the action to perform when a user asks for data in the cache and the cache doesn't yet know about the key. when it runs, the commandprefix gets three additional arguments, in this order:

1. the string get
2. the key requested
3. the cache object itself — in the form of its object command

and the execution of that action happens in an idle-handler, which decouples it from the original request. cute, right?

the only supported option is:

• -full-async-results — this one defines how the cache behaves when the requested keys are already known to the cache at the time of the get request. by default, those requests get responded to asynchronously as well. setting this option to false forces the cache to respond to them synchronously — although still through the specified callback. lowkey a big deal.

---

🌈 the object commands

the object commands created by the class commands above have this form:

🎀 objectName get key donecmdprefix

this method requests the data for the key from the cache. if the data isn't known yet, the command prefix you specified during construction of the cache object gets used to ask for that information. teamwork!

whenever the information is/becomes available, the donecmdprefix gets run to transfer the result to the caller. this command prefix is invoked with either 2 or 3 arguments, i.e.

1. the string set, the key, and the value.
2. the string unset, and the key.

these two possibilities are how it either signals the value for the key, or signals that the key has no value defined for it. and bestie, that second one is distinct from the cache not knowing about the key at all. different thing entirely. 💀

for a cache object configured to be fully asynchronous (the default), the donecmdprefix is always run in an idle-handler, decoupling it from the request. otherwise the callback gets invoked synchronously when the key is known to the cache at the time of the invocation.

another important part of the cache's behaviour: because it's asynchronous, it's possible that multiple get requests get issued for the same key before it can respond. in that case the cache issues only one data request to the provider — for the first of these — and suspends the others, and then notifies all of them when the data becomes available. efficiency icon behaviour. periodt.

🧚 objectName set key value

🧚 objectName unset key

these two methods exist so that users of the cache can make keys known to the cache — either as having a value, or as undefined.

it's expected that the data provider (see commandprefix of the constructor) uses them in response to data requests for unknown keys.

and notice how this matches the cache's own API towards its caller: calling the donecmd of get-requests issued to itself with either "set key value" or "unset key", versus issuing get-requests to its own provider with itself in the place of the donecmd, expecting to be called with either "set key value" or "unset key". mirrored. symmetrical. iconic. ✨

this also means that these methods invoke the donecmd of all get-requests waiting for information about the modified key. everybody gets notified. group chat energy fr fr.

🍓 objectName exists key

this method queries the cache for knowledge about the key and returns a boolean value. the result is true if the key is known, and false otherwise. simple. clean. we love her.

💜 objectName clear ?key?

this method resets the state of either the specified key or all keys known to the cache, making it unknown. which forces future get-requests to reload the information from the provider. fresh start, no baggage, we're rebranding. 🌸

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving humble. please report such in the category cache of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also report any ideas for enhancements you may have for either the package and/or the documentation. we're listening 🫶

when proposing code changes, please provide unified diffs, i.e the output of diff -u.

also note: attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

---

⭐ KEYWORDS ⭐

asynchronous, cache, callback, synchronous

---

🌈 COPYRIGHT 🌈

Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page bestie 💅 this came to you from tcllib, version 0.3.2, in the cache::async(3tcl) manual. go forth and cache asynchronously, you absolute legend 👑✨