pcache

Documentation

Overview

Package pcache provides a lock-free provider information cache for high performance concurrent reads.

ProviderCache caches provider information from one or more sources of information. Cached data is looked up and returned concurrently without lock contention. This enables services that require high-frequency concurrent cache reads, such as those that must quickly deliver IPNI find results, or that handle a high volume of provider information requests.

Multiple Overlapping Data Sources

The cache can be configured with multiple data sources from which provider information is fetched. If the same provider information is returned from multiple data sources, then the information with the most recent timestamp is used.

All Provider Information Cached

The provider cache maintains a unified view of all provider information across all data sources. Caching provider information in builk allows the cached data to be refreshed with fewer fetches over the network, then if information was fetched for individual providers. This is particularly important when there are multiple sources to fetch provider information from, and when responses include infomration about multiple providers.

Cache Refresh

If the cache refresh interval is non-zero (default is 2 minutes), then after that time is elapsed, a timer sets a flag to indicate that refresh is required. The next cache lookup checks the flag and if set, begins a refresh asynchronously (in the background). When the refresh is done, the cached read-only data is updates and the refresh timer is reset. This way there is no need to have a separate goroutine to manage, and no unnecessary refresh work is done if the cache is not actively used. A refresh can also be explicitly requested.

Each refresh updates provider information from all sources. An updated view of the cached data is built, and is then atomically set as the cache's read-only lock-free data.

Negative Cache

Lookups for provider information that are not currently cached will generate an initial query to the cache's data sources. If the information is found then it is cached. If not, a negative cache entry is cached. The negative cache entry prevents subsequent queries for the same provider from querying data sources. If the information becomes available the negative cache entry is replaced at the next refresh.

Cache Eviction

Cached provider information remains in the cache until the information is no longer available from any of the sources for longer than the configured time-to-live. The time-to-live countdown begins when the information is no longer seen from any source. Negative cache entries are also evicted after having been in the cache for the time-to-live.

Index

• Variables
• type Option
  • func WithClient(c *http.Client) Option
  • func WithPreload(preload bool) Option
  • func WithRefreshInterval(interval time.Duration) Option
  • func WithSource(src ...ProviderSource) Option
  • func WithSourceURL(urls ...string) Option
  • func WithTTL(ttl time.Duration) Option
• type ProviderCache
  • func New(options ...Option) (*ProviderCache, error)
  • func (pc *ProviderCache) Get(ctx context.Context, pid peer.ID) (*model.ProviderInfo, error)
  • func (pc *ProviderCache) GetResults(ctx context.Context, pid peer.ID, ctxID, metadata []byte) ([]model.ProviderResult, error)
  • func (pc *ProviderCache) Len() int
  • func (pc *ProviderCache) List() []*model.ProviderInfo
  • func (pc *ProviderCache) Refresh(ctx context.Context) error
• type ProviderSource
  • func NewHTTPSource(srcURL string, client *http.Client) (ProviderSource, error)

Variables

var ErrClosed = errors.New("cache closed")

Types

type Option

type Option func(*config) error

Option is a function that sets a value in a config.

func WithClient

func WithClient(c *http.Client) Option

WithClient sets the HTTP client to use when WithSourceURL is used.

func WithPreload

func WithPreload(preload bool) Option

WithPreload enables or disabled cache preload. Preload performs an initial refresh of the cache to populate it. This results in faster lookup times when information for multiple providers will be needed, even for a few providers. Generally, preload should always be enabled, but can be disabled if there are specific situations that require it.

Default is true (enabled).

func WithRefreshInterval

func WithRefreshInterval(interval time.Duration) Option

WithRefreshInterval sets the minimul time interval to wait between automatic cache refreshes. Once the interval has elapsed since the last refresh, an new refresh is started at nest cache Get. If set to 0, then automatic refresh is disabled.

Default is 2 minutes.

func WithSource

func WithSource(src ...ProviderSource) Option

WithSource adds one or more new provider information sources for the cache to pull provider information from. If multiple sources provide the information for the same providers, then the provider record with the most recent LastAdvertisementTime is uesd.

func WithSourceURL

func WithSourceURL(urls ...string) Option

WithSourceURL adds one or more new HTTP sources of provider information. It is a convenient alternative to calling NewHTTPSource and WithSource for each source URL. To use an alternative HTTP client with each source, call WithClient first.

func WithTTL

func WithTTL(ttl time.Duration) Option

WithTTL sets the time that provider information remains in the cache after it is not longer available from any of the original sources. The time should be long enough to cover temporary unavailability of sources.

This is also the amount of time that a negative cache entry will remain in the cache before being removed at the next refresh.

Default is 10 minutes.

type ProviderCache

type ProviderCache struct {
	// contains filtered or unexported fields
}

ProviderCache is a lock-free provider information cache for high-performance concurrent reads.

func New

func New(options ...Option) (*ProviderCache, error)

New creates a new provider cache.

func (*ProviderCache) Get

func (pc *ProviderCache) Get(ctx context.Context, pid peer.ID) (*model.ProviderInfo, error)

func (*ProviderCache) GetResults

func (pc *ProviderCache) GetResults(ctx context.Context, pid peer.ID, ctxID, metadata []byte) ([]model.ProviderResult, error)

GetResults retrieves information about the provider specified by peer ID and composes a slice of ProviderResults for the provider and any extended providers. If provider information is not available, then a nil slice is returned. An error results from the context being canceled or the cache closing.

func (*ProviderCache) Len

func (pc *ProviderCache) Len() int

func (*ProviderCache) List

func (pc *ProviderCache) List() []*model.ProviderInfo

func (*ProviderCache) Refresh

func (pc *ProviderCache) Refresh(ctx context.Context) error

Refresh initiates an immediate cache refresh.

type ProviderSource

type ProviderSource interface {
	// Fetch gets provider information for a specific provider.
	Fetch(context.Context, peer.ID) (*model.ProviderInfo, error)
	// Fetch gets provider information for all providers.
	FetchAll(context.Context) ([]*model.ProviderInfo, error)
	// String returns a description of the source.
	String() string
}

ProviderSource in an interface that the cache uses to fetch provider information. Each ProviderSource is a specific supplier of provider information. The cache can be configured with any number of sources that supply provider information.

func NewHTTPSource

func NewHTTPSource(srcURL string, client *http.Client) (ProviderSource, error)