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
- type ProviderCache
- 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
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("cache closed")
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*config) error
Option is a function that sets a value in a config.
func WithClient ¶
WithClient sets the HTTP client to use when WithSourceURL is used.
func WithPreload ¶
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 ¶
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 ¶
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 ¶
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 (*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
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)
Source Files