CoreCache.transactionLookup
Perform a transactional lookup into the cache, returning a TransactionCacheEntry
instance.
Transactions coordinate between concurrent actions on the same cache key, incorporating concepts of request collapsing and revalidation, though at a lower level that does not automatically interpret HTTP semantics.
Request Collapsing:
If there are multiple concurrent calls to CoreCache.transactionLookup()
for the same item and that item is not present,
just one of the callers will be instructed to insert the item into the cache as part of the transaction.
The other callers will block until the metadata for the item has been inserted, and can then begin streaming its contents out of the cache at the same time that the inserting caller streams them into the cache.
Revalidation:
Similarly, if an item is usable but stale, and multiple callers attempt a CoreCache.transactionLookup()
concurrently, they will all be given access to the stale item, but only one will be designated to perform an asynchronous update (or insertion) to freshen the item in the cache.
Syntax
transactionLookup(key, options)
Parameters
key
: string- A cache key which is a string with a length of up to 8,135 that identify a cached item.
- The cache key may not uniquely identify an item; headers can be used to augment the key when multiple items are associated with the same key.
options
: objectheaders
: HeadersInit optional- The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via the
vary
property withinTransactionInsertOptions
. - A lookup will succeed when there is at least one cached item that matches lookup’s
key
, and all of the lookup’s headers included in the cache items’vary
list match the corresponding headers in that cached item. - A typical example is a cached HTTP response, where the request had an "Accept-Encoding" header. In that case, the origin server may or may not decide on a given encoding, and whether that same response is suitable for a request with a different (or missing) Accept-Encoding header is determined by whether Accept-Encoding is listed in Vary header in the origin’s response.
- Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the HTTP Vary header.
- The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via the
Return value
Returns an instance of TransactionCacheEntry
.
Exceptions
TypeError
- If the provided
key
:- Is an empty string
- Cannot be coerced to a string
- Is longer than 8135 characters
- If the provided