fastly::cache::core::Found Class Reference

#include <core.h>

Public Member Functions
std::chrono::nanoseconds	age () const
	The current age of the cached item.
std::chrono::nanoseconds	max_age () const
std::chrono::nanoseconds	remaining_ttl () const
std::chrono::nanoseconds	stale_while_revalidate () const
bool	is_stale () const
bool	is_usable () const
uint64_t	hits () const
std::optional< uint64_t >	known_length () const
std::vector< uint8_t >	user_metadata () const
	The user-controlled metadata associated with the cached item.
tl::expected< Body, CacheError >	to_stream () const
tl::expected< Body, CacheError >	to_stream_from_range (std::optional< uint64_t > from, std::optional< uint64_t > to) const

Friends
class	Transaction
class	LookupBuilder
class	TransactionInsertBuilder
class	ReplaceBuilder

Detailed Description

Represents a found cached item. This allows access to metadata and the cached body.

A Found instance is returned from Transaction::found() when the transaction has found a cached item during the lookup operation.

Member Function Documentation

age()

std::chrono::nanoseconds fastly::cache::core::Found::age

(

)

const

The current age of the cached item.

hits()

uint64_t fastly::cache::core::Found::hits

(

)

const

Determines the number of cache hits to this cached item.

Note: this hit count only reflects the view of the server that supplied the cached item. Due to clustering, this count may vary between potentially many servers within the data center where the item is cached. See the clustering documentation for details, though note that the exact caching architecture of Compute is different from VCL services.

is_stale()

bool fastly::cache::core::Found::is_stale

(

)

const

Determines whether the cached item is stale.

A cached item is stale if its age is greater than its max-age period.

is_usable()

bool fastly::cache::core::Found::is_usable

(

)

const

Determines whether the cached item is usable.

A cached item is usable if its age is less than the sum of the max-age and stale-while-revalidate periods.

known_length()

std::optional< uint64_t > fastly::cache::core::Found::known_length

(

)

const

The size in bytes of the cached item, if known.

The length of the cached item may be unknown if the item is currently being streamed into the cache without a fixed length.

max_age()

std::chrono::nanoseconds fastly::cache::core::Found::max_age

(

)

const

How long the cached item is/was considered fresh, starting from the start of the cached item's lifetime.

Note that this is the maximum possible age, not the freshness time remaining; see remaining_ttl() for that.

remaining_ttl()

std::chrono::nanoseconds fastly::cache::core::Found::remaining_ttl

(

)

const

Returns the remaining TTL: how long this cached item has left before it is considered stale. Zero if the cached item is stale.

Note: this reports the remaining freshness period; max_age() reports the maximum possible TTL.

stale_while_revalidate()

std::chrono::nanoseconds fastly::cache::core::Found::stale_while_revalidate

(

)

const

The time for which a cached item can safely be used despite being considered stale.

to_stream()

tl::expected< Body, CacheError > fastly::cache::core::Found::to_stream

(

)

const

Retrieves the entire cached item as a Body that can be read in a streaming fashion.

Only one stream can be active at a time for a given Found. The stream must be fully consumed (read) before a new stream can be created from the same Found. CacheError::InvalidOperation will be returned if a stream is already active for this Found. This restriction may be lifted in future releases.

to_stream_from_range()

tl::expected< Body, CacheError > fastly::cache::core::Found::to_stream_from_range	(	std::optional< uint64_t >	from,
		std::optional< uint64_t >	to ) const

Retrieves a range of bytes from the cached item as a Body that can be read in a streaming fashion.

from and to will determine which bytes are returned:

• If from is provided and to is not provided, the stream will begin at the from byte and continue to the end of the body.
• If from and to are both provided, only the range from..=to will be provided. Note, both ends are inclusive.
• If to is provided but from is not provided, the last to bytes of the body will be provided.

Inherently invalid ranges

If to is strictly before from, this call returns an error immediately. (to == from is acceptable - the bounds are inclusive, so this addresses a single byte.)

Known size

The size of a cached item is known if it has completed streaming or if the expected length was provided at insert time (TransactionInsertBuilder::known_length and similar).

If the size of the cached item is known, the range is respected only if the range is valid (to is after from, and both ranges are less than or equal to the size of the item). Otherwise, no error is returned, and the entire body is returned instead.

Unknown size

The size of a cached item may not be known (if known_length was not provided and the body is still being streamed). If the size of the cached item is unknown, by default, the range is ignored, and the entire cached item is returned.

This behavior can be overriden by calling TransactionLookupBuilder::always_use_requested_range. If provided, this call will block until the start of the interval is found, then begin streaming content. The Body will generate a read error if the end of the range exceeds the available data.

user_metadata()

std::vector< uint8_t > fastly::cache::core::Found::user_metadata

(

)

const

The user-controlled metadata associated with the cached item.

Friends And Related Symbol Documentation

LookupBuilder

friend class LookupBuilder

friend

ReplaceBuilder

friend class ReplaceBuilder

friend

Transaction

friend class Transaction

friend

TransactionInsertBuilder

friend class TransactionInsertBuilder

friend

---

The documentation for this class was generated from the following file:

• include/fastly/cache/core.h