cache::async(n)

💖 cache::async(n) — the manual, but make it cute 💖

okay bestie, listen up — this is the manual page for cache::async, straight out of the In-memory caches section of the Tcl man pages. It's a Tcl thing. It's a cache thing. It's a whole vibe. Let's get into it. 🦋

---

✨ NAME ✨

cache::async — Asynchronous in-memory cache. That's the whole name, no notes. 💅

---

🌸 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?

look at all those little lines. gorgeous. iconic. no cap. ✨

---

💜 DESCRIPTION 💜

So basically 💁‍♀️ this package hands you objects that cache data in memory, and the way they talk to you is asynchronous — requests and responses are decoupled, they're not just sitting there waiting on each other like some synchronous situationship. 🙈

These objects are agnostic about cache keys and cache values — they literally do not care what you put in them, bestie, they support you. 🫶 And any unknown methods get delegated to the provider of cached data.

Those two properties together? chef's kiss. It means you can use a cache as a facade for any data provider. Like, any one. Slay. 👑

---

🎀 API 🎀

The package exports a class, cache::async, as specified below. (yes, the whole class. she's exported. she's available. she's ready.)

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

This command creates a new cache object with an associated global Tcl command whose name is objectName. That command is your girl — you use it to invoke various operations on the object. 💅

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 gets run, the commandprefix is handed three additional arguments, in this exact 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 the action happens in an idle-handler, which decouples it from the original request. ✨ (decoupling! we love decoupling! it's giving boundaries!)

The only supported option is:

• -full-async-results — this option defines the behaviour of the cache for when requested keys are known to the cache at the time of the get request. By default, such requests are responded to asynchronously as well. Setting this option to false forces the cache to respond to them synchronously — although still through the specified callback, so don't get it twisted. 😌

⚠️ heads up bestie: that's the only supported option. Just the one. Don't go looking for friends. 🙈

The object commands created by the class commands above have the 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 specified during construction of the cache object is used to ask for that information. 🦋

Whenever the information is/becomes available, the donecmdprefix will be 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 signals either the value for the key, or that the key has no value defined for it. And the latter is distinct from the cache not knowing about the key — those are two different things, bestie, don't conflate them, it's a whole different situation. 😭

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

Another important part of the cache's behaviour: because it's asynchronous, it is possible that multiple get requests are issued for the same key before it can respond. In that case the cache will issue only one data request to the provider — for the first of these — and suspend the others, and then notify all of them when the data becomes available.

🔥 that's called efficiency, and she ate. one request, everybody fed. periodt. 💅

🌸 objectName set key value

🌸 objectName unset key

These two methods are provided so that users of the cache can make keys known to the cache — either as having a value, or as undefined. 🫶

It is expected that the data provider (see commandprefix of the constructor) uses them in response to data requests for unknown keys. Like, that's the assignment. that's the job. 🎀

Now note 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.

it's symmetric. it's recursive-ish. it's a mirror situation. iykyk. ✨

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

🦋 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. no drama. 💅

👑 objectName clear ?key?

This method resets the state of either the specified key or of all keys known to the cache, making it unkown. This forces future get-requests to reload the information from the provider.

💀 fresh start energy. sometimes you just gotta clear the whole thing and begin again. we've all been there.

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

This document, and the package it describes, will undoubtedly contain bugs and other problems. ngl, that's just how software is. 😭 Please report such in the category cache of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. they want your ideas, bestie. your brain is valuable. 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u. (exact command. exact flags. don't improvise. 💅)

Note further that 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.

✨ lowkey a whole navigation tutorial. but it's useful. it's giving directions. we appreciate directions. 🎀

---

🌈 KEYWORDS 🌈

asynchronous, cache, callback, synchronous

(four keywords. four little vibes. all of them correct.)

---

💜 COPYRIGHT 💜

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

---

and that's the whole page, bestie!! 🎉 this lovely thing is from tcllib, version 0.3.2, and it lives in the cache::async(n) manual. thank you for reading, you're doing amazing, go cache something asynchronously, mwah 💖✨🦋