Skip to content

Fix functions cache example #2054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 21, 2021
Merged

Fix functions cache example #2054

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5db4a28
Merge pull request #2052 from segmentio/develop
stayseesong Oct 21, 2021
9bd394c
Functions: Fix cache example
tysonmote Oct 21, 2021
fc3112c
Functions: Clarify behavior and limits of cache
tysonmote Oct 21, 2021
a152fd0
update verbiage
Oct 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions src/_includes/content/functions/runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,18 +31,24 @@ Only the [`crypto` Node.js module](https://nodejs.org/dist/latest-v10.x/docs/api

##### Caching

Per-function global caching is available in the `cache` namespace. The following functions are available:
Basic cache storage is available through the `cache` object, which has the following methods defined:

- `cache.load(key: string, ttl: number, fn: async () => any): Promise<any>`
- Obtains a cached value for the provided `key`, invoking the callback if the value is missing or has expired. The `ttl` is the maximum duration in milliseconds the value can be cached. If omitted or set to `-1`, the value will have no expiry. There is no guarantee that a value will be retained in the cache for the provided duration, however. The cache space is limited, so efforts to minimize the cached value size will afford a higher cache hit ratio.
- Obtains a cached value for the provided `key`, invoking the callback if the value is missing or has expired. The `ttl` is the maximum duration in milliseconds the value can be cached. If omitted or set to `-1`, the value will have no expiry.
- `cache.delete(key: string): void`
- Forcefully remove the value associated with the `key`.
- Immediately remove the value associated with the `key`.

Some important notes about the cache:

- When testing functions in the code editor, the cache will be empty because each test temporarily deploys a new instance of the function.
- Values in the cache are not shared between concurrently-running function instances; they are process-local which means that high-volume functions will have many separate caches.
- Values may be expunged at any time, even before the configured TTL is reached. This can happen due to memory pressure or normal scaling activity. Minimizing the size of cached values can improve your hit/miss ratio.
- Functions that receive a low volume of traffic may be temporarily suspended, during which their caches will be emptied. In general, caches are best used for high-volume functions and with long TTLs.
The following example gets a JSON value through the cache, only invoking the callback as needed:

```js
const ttl = 5 * 60 * 1000 // 5 minutes
const val = await cache.load("mycachekey", ttl, () => {
const val = await cache.load("mycachekey", ttl, async () => {
const res = await fetch("http://echo.jsontest.com/key/value/one/two")
const data = await res.json()
return data
Expand Down