cache

package module
v8.0.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 23, 2022 License: ISC Imports: 14 Imported by: 1

Documentation

Overview

Package cache provides a number of types and functions for caching Decred address data, and filtering AddressRow slices. The type AddressCache may store the following data for an address: balance (see db/dbtypes.AddressBalance), address table row data (see db/dbtypes.AddressRow), merged address table row data, UTXOs (see db/dbtypes.AddressTxnOutput), and "metrics" (see db/dbtypes.AddressMetrics).

Index

Constants

View Source
const (
	BlockSize       = "block-size"
	BlockChainSize  = "blockchain-size"
	ChainWork       = "chainwork"
	CoinSupply      = "coin-supply"
	DurationBTW     = "duration-btw-blocks"
	HashRate        = "hashrate"
	POWDifficulty   = "pow-difficulty"
	TicketPrice     = "ticket-price"
	TxCount         = "tx-count"
	Fees            = "fees"
	AnonymitySet    = "privacy-participation"
	TicketPoolSize  = "ticket-pool-size"
	TicketPoolValue = "ticket-pool-value"
	WindMissedVotes = "missed-votes"
	PercentStaked   = "stake-participation"
)

Keys for specifying chart data type.

View Source
const (
	DayBin     binLevel = "day"
	BlockBin   binLevel = "block"
	WindowBin  binLevel = "window"
	HeightAxis axisType = "height"
	TimeAxis   axisType = "time"
)

These are the recognized binLevel and axisType values.

View Source
const (

	// HashrateAvgLength is the number of blocks used the rolling average for
	// the network hashrate calculation.
	HashrateAvgLength = 120
)
View Source
const InvalidBinErr = ChartError("invalid bin")

InvalidBinErr is returned when a ChartMaker receives an unknown BinLevel. In practice, this should be impossible, since ParseBin returns a default if a supplied bin specifier is invalid, and window-binned ChartMakers ignore the bin flag.

View Source
const UnknownChartErr = ChartError("unknown chart")

UnknownChartErr is returned when a chart key is provided that does not match any known chart type constant.

Variables

View Source
var DefaultBinLevel = DayBin

DefaultBinLevel will be used if a bin level is not specified to (*ChartData).Chart (via empty string), or if the provided BinLevel is invalid.

Functions

func AllCreditAddressRows

func AllCreditAddressRows(rows []*dbtypes.AddressRow) []*dbtypes.AddressRow

AllCreditAddressRows returns all of the credit (funding) address rows from the given AddressRow slice.

func AllDebitAddressRows

func AllDebitAddressRows(rows []*dbtypes.AddressRow) []*dbtypes.AddressRow

AllDebitAddressRows returns all of the debit (!funding) address rows from the given AddressRow slice.

func CountCreditDebitRows

func CountCreditDebitRows(rows []*dbtypes.AddressRow) (numCredit, numDebit int)

CountCreditDebitRows returns the numbers of credit (funding) and debit (!funding) address rows in a []*dbtypes.AddressRow.

func CountCreditDebitRowsCompact

func CountCreditDebitRowsCompact(rows []*dbtypes.AddressRowCompact) (numCredit, numDebit int)

CountCreditDebitRowsCompact returns the numbers of credit (funding) and debit (!funding) address rows in a []dbtypes.AddressRowCompact.

func CountCreditDebitRowsMerged

func CountCreditDebitRowsMerged(rows []*dbtypes.AddressRowMerged) (numCredit, numDebit int)

CountCreditDebitRowsMerged returns the numbers of credit (funding) and debit (!funding) address rows in a []dbtypes.AddressRowMerged.

func CreditAddressRows

func CreditAddressRows(rows interface{}, N, offset int) interface{}

CreditAddressRows returns up to N credit (funding) address rows from the given AddressRow slice, starting after skipping offset rows. The input rows may only be of type []dbtypes.AddressRowCompact or []dbtypes.AddressRowMerged. The same type is returned, unless the input type is unrecognized, in which case a nil interface is returned.

func DebitAddressRows

func DebitAddressRows(rows interface{}, N, offset int) interface{}

DebitAddressRows returns up to N debit (!funding) address rows from the given AddressRow slice, starting after skipping offset rows. The input rows may only be of type []dbtypes.AddressRowCompact or []dbtypes.AddressRowMerged. The same type is returned, unless the input type is unrecognized, in which case a nil interface is returned.

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func ParseAxis

func ParseAxis(aType string) axisType

ParseAxis returns the matching axis type, else the default of time axis.

func ParseBin

func ParseBin(bin string) binLevel

ParseBin will return the matching bin level, else the default bin.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info.

func ValidateLengths

func ValidateLengths(lens ...lengther) (int, error)

ValidateLengths checks that the length of all arguments is equal.

Types

type AddressCache

type AddressCache struct {
	ProjectAddress string
	// contains filtered or unexported fields
}

AddressCache maintains a store of address data. Use NewAddressCache to create a new AddressCache with initialized internal data structures.

func NewAddressCache

func NewAddressCache(rowCapacity, addressCapacity, utxoCapacityBytes int) *AddressCache

NewAddressCache constructs an AddressCache with capacity for the specified number of address rows. rowCapacity is an absolute limit on the number of address data table rows that may have cached data, while addressCapacity is a limit on the number of unique addresses in the cache, regardless of the number of rows. utxoCapacityBytes is the capacity in bytes of the UTXO cache.

func (*AddressCache) Balance

func (ac *AddressCache) Balance(addr string) (*dbtypes.AddressBalance, *BlockID)

Balance attempts to retrieve an AddressBalance for the given address. The BlockID for the block at which the cached data is valid is also returned. In the event of a cache miss, both returned pointers will be nil.

func (*AddressCache) BalanceStats

func (ac *AddressCache) BalanceStats() (hits, misses int)

BalanceStats reports the balance hit/miss stats.

func (*AddressCache) Clear

func (ac *AddressCache) Clear(addrs []string) (numCleared int)

Clear purging cached data for the given addresses. If addrs is nil, all data are cleared. If addresses is non-nil empty slice, no data are cleared.

func (*AddressCache) ClearAll

func (ac *AddressCache) ClearAll() (numCleared int)

ClearAll resets AddressCache, purging all cached data.

func (*AddressCache) ClearRows

func (ac *AddressCache) ClearRows(addr string)

ClearRows clears any stored address rows for the given address in cache.

func (*AddressCache) ClearUTXOs

func (ac *AddressCache) ClearUTXOs(addr string)

ClearUTXOs clears any stored UTXOs for the given address in cache.

func (*AddressCache) HistoryChart

func (ac *AddressCache) HistoryChart(addr string, addrChart dbtypes.HistoryChart,
	chartGrouping dbtypes.TimeBasedGrouping) (*dbtypes.ChartsData, *BlockID)

HistoryChart attempts to retrieve ChartsData for the given address, chart type, and grouping interval. The BlockID for the block at which the cached data is valid is also returned. In the event of a cache miss, both returned pointers will be nil.

func (*AddressCache) HistoryStats

func (ac *AddressCache) HistoryStats() (hits, misses int)

HistoryStats reports the history data hit/miss stats.

func (*AddressCache) Length

func (ac *AddressCache) Length() (numAddrs, numTxns, numUTXOs int)

Length returns the total number of address rows and UTXOs stored in cache.

func (*AddressCache) NumAddresses

func (ac *AddressCache) NumAddresses() int

NumAddresses returns the total number of addresses in the cache.

func (*AddressCache) NumRows

func (ac *AddressCache) NumRows(addr string) (int, *BlockID)

NumRows returns the number of non-merged rows. If the rows are not cached, a count of -1 and *BlockID of nil are returned.

func (*AddressCache) Reporter

func (ac *AddressCache) Reporter()

Reporter prints the number of cached addresses, rows, and utxos, as well as a table of cache hits and misses.

func (*AddressCache) RowStats

func (ac *AddressCache) RowStats() (hits, misses int)

RowStats reports the row hit/miss stats.

func (*AddressCache) Rows

func (ac *AddressCache) Rows(addr string) ([]*dbtypes.AddressRowCompact, *BlockID)

Rows attempts to retrieve an []*AddressRow for the given address. The BlockID for the block at which the cached data is valid is also returned. In the event of a cache miss, the slice and the *BlockID will be nil.

func (*AddressCache) StoreBalance

func (ac *AddressCache) StoreBalance(addr string, balance *dbtypes.AddressBalance, block *BlockID) bool

StoreBalance stores the AddressBalance for the given address in cache. The current best block data is required to determine cache freshness.

func (*AddressCache) StoreHistoryChart

func (ac *AddressCache) StoreHistoryChart(addr string, addrChart dbtypes.HistoryChart,
	chartGrouping dbtypes.TimeBasedGrouping, cd *dbtypes.ChartsData, block *BlockID) bool

StoreHistoryChart stores the charts data for the given address in cache. The current best block data is required to determine cache freshness.

func (*AddressCache) StoreRows

func (ac *AddressCache) StoreRows(addr string, rows []*dbtypes.AddressRow, block *BlockID) bool

StoreRows stores the non-merged AddressRow slice for the given address in cache. The current best block data is required to determine cache freshness.

func (*AddressCache) StoreRowsCompact

func (ac *AddressCache) StoreRowsCompact(addr string, rows []*dbtypes.AddressRowCompact, block *BlockID) bool

StoreRowsCompact stores the non-merged AddressRow slice for the given address in cache. The current best block data is required to determine cache freshness.

func (*AddressCache) StoreUTXOs

func (ac *AddressCache) StoreUTXOs(addr string, utxos []*dbtypes.AddressTxnOutput, block *BlockID) bool

StoreUTXOs stores the *AddressTxnOutput slice for the given address in cache. The current best block data is required to determine cache freshness.

func (*AddressCache) Transactions

func (ac *AddressCache) Transactions(addr string, N, offset int64, txnType dbtypes.AddrTxnViewType) ([]*dbtypes.AddressRow, *BlockID, error)

Transactions attempts to retrieve transaction data for the given address and view (merged or not, debit/credit/all). Like the DB queries, the number of transactions to retrieve, N, and the number of transactions to skip, offset, are also specified.

func (*AddressCache) TransactionsCompact

func (ac *AddressCache) TransactionsCompact(addr string, N, offset int64, txnType dbtypes.AddrTxnViewType) ([]*dbtypes.AddressRowCompact, *BlockID, error)

TransactionsCompact is like Transactions, but it must be used with a non-merged AddrTxnViewType, and it returns a []dbtypes.AddressRowCompact. A cache miss is indicated by (*BlockID)==nil. The retured rows may be nil or an empty slice for a cache hit if the address has no history.

func (*AddressCache) TransactionsMerged

func (ac *AddressCache) TransactionsMerged(addr string, N, offset int64, txnType dbtypes.AddrTxnViewType) ([]*dbtypes.AddressRowMerged, *BlockID, error)

TransactionsMerged is like Transactions, but it must be used with a merged AddrTxnViewType, and it returns a []dbtypes.AddressRowMerged. A cache miss is indicated by (*BlockID)==nil. The retured rows may be nil or an empty slice for a cache hit if the address has no history.

func (*AddressCache) UTXOs

func (ac *AddressCache) UTXOs(addr string) ([]*dbtypes.AddressTxnOutput, *BlockID)

UTXOs attempts to retrieve an []*AddressTxnOutput for the given address. The BlockID for the block at which the cached data is valid is also returned. In the event of a cache miss, the slice and the *BlockID will be nil.

func (*AddressCache) UtxoStats

func (ac *AddressCache) UtxoStats() (hits, misses int)

UtxoStats reports the utxo hit/miss stats.

type AddressCacheItem

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

AddressCacheItem is the unit of cached data pertaining to a certain address. The height and hash of the best block at the time the data was obtained is stored to determine validity of the cache item. Cached data for an address are: balance, all non-merged address table rows, all merged address table rows, all UTXOs, and address metrics.

func (*AddressCacheItem) Balance

func (d *AddressCacheItem) Balance() (*dbtypes.AddressBalance, *BlockID)

Balance is a thread-safe accessor for the *dbtypes.AddressBalance.

func (*AddressCacheItem) BlockHash

func (d *AddressCacheItem) BlockHash() chainhash.Hash

BlockHash is a thread-safe accessor for the block hash.

func (*AddressCacheItem) BlockHeight

func (d *AddressCacheItem) BlockHeight() int64

BlockHeight is a thread-safe accessor for the block height.

func (*AddressCacheItem) HistoryChart

func (d *AddressCacheItem) HistoryChart(addrChart dbtypes.HistoryChart, chartGrouping dbtypes.TimeBasedGrouping) (*dbtypes.ChartsData, *BlockID)

HistoryChart is a thread-safe accessor for the TxHistory.

func (*AddressCacheItem) NumRows

func (d *AddressCacheItem) NumRows() (int, *BlockID)

NumRows returns the number of non-merged rows. If the rows are not cached, a count of -1 and *BlockID of nil are returned.

func (*AddressCacheItem) Rows

func (d *AddressCacheItem) Rows() ([]*dbtypes.AddressRowCompact, *BlockID)

Rows is a thread-safe accessor for the []dbtypes.AddressRowCompact.

func (*AddressCacheItem) SetBalance

func (d *AddressCacheItem) SetBalance(block BlockID, balance *dbtypes.AddressBalance)

SetBalance updates the cache item for the given AddressBalance valid at the given BlockID.

func (*AddressCacheItem) SetRows

func (d *AddressCacheItem) SetRows(block BlockID, rows []*dbtypes.AddressRowCompact)

SetRows updates the cache item for the given non-merged AddressRow slice valid at the given BlockID.

func (*AddressCacheItem) SetUTXOs

func (d *AddressCacheItem) SetUTXOs(block BlockID, utxos []*dbtypes.AddressTxnOutput)

SetUTXOs updates the cache item for the given *AddressTxnOutput slice valid at the given BlockID.

func (*AddressCacheItem) Transactions

func (d *AddressCacheItem) Transactions(N, offset int, txnView dbtypes.AddrTxnViewType) (interface{}, *BlockID, error)

Transactions attempts to retrieve transaction data for the given view (merged or not, debit/credit/all). Like the DB queries, the number of transactions to retrieve, N, and the number of transactions to skip, offset, are also specified.

func (*AddressCacheItem) UTXOs

func (d *AddressCacheItem) UTXOs() ([]*dbtypes.AddressTxnOutput, *BlockID)

UTXOs is a thread-safe accessor for the []*dbtypes.AddressTxnOutput.

type BlockID

type BlockID struct {
	Hash   chainhash.Hash
	Height int64
}

BlockID provides basic identifying information about a block.

func NewBlockID

func NewBlockID(hash *chainhash.Hash, height int64) *BlockID

NewBlockID constructs a new BlockID.

type CacheLock

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

CacheLock is a "try lock" for coordinating multiple accessors, while allowing only a single updater. Use NewCacheLock to create a CacheLock.

func NewCacheLock

func NewCacheLock() *CacheLock

NewCacheLock constructs a new CacheLock.

func (*CacheLock) TryLock

func (cl *CacheLock) TryLock(addr string) (busy bool, wait chan struct{}, done func())

TryLock will attempt to obtain an exclusive lock and a function to release the lock. If the lock is already held, the channel returned by TryLock will be closed when/if the holder of the lock calls the done function.

Trylock returns a bool, busy, indicating if another caller has already obtained the lock. When busy is false, the caller has obtained the exclusive lock, and the returned func(), done, should be called when ready to release the lock. When busy is true, the returned channel, wait, should be received from to block until the updater has released the lock.

type ChartData

type ChartData struct {
	DiffInterval int32
	StartPOS     int32
	Blocks       *zoomSet
	Windows      *windowSet
	Days         *zoomSet
	// contains filtered or unexported fields
}

ChartData is a set of data used for charts. It provides methods for managing data validation and update concurrency, but does not perform any data retrieval and must be used with care to keep the data valid. The Blocks and Windows fields must be updated by (presumably) a database package. The Days data is auto-generated from the Blocks data during Lengthen-ing.

func NewChartData

func NewChartData(ctx context.Context, height uint32, chainParams *chaincfg.Params) *ChartData

NewChartData constructs a new ChartData.

func (*ChartData) AddUpdater

func (charts *ChartData) AddUpdater(updater ChartUpdater)

AddUpdater adds a ChartUpdater to the Updaters slice. Updaters are run sequentially during (*ChartData).Update.

func (*ChartData) AnonymitySetTip

func (charts *ChartData) AnonymitySetTip() int32

AnonymitySetTip is the height of the anonymity set

func (*ChartData) Chart

func (charts *ChartData) Chart(chartID, binString, axisString string) ([]byte, error)

Chart will return a JSON-encoded chartResponse of the provided chart, binLevel, and axis (TimeAxis, HeightAxis). binString is ignored for window-binned charts.

func (*ChartData) Dump

func (charts *ChartData) Dump(dumpPath string)

Dump dumps a ChartGobject to a gob file at the given path.

func (*ChartData) FeesTip

func (charts *ChartData) FeesTip() int32

FeesTip is the height of the Fees data.

func (*ChartData) Height

func (charts *ChartData) Height() int32

Height is the height of the blocks data. Data is assumed to be complete and without extraneous entries, which means that the (zoomSet).Height does not need to be populated for (ChartData).Blocks because the height is just len(Blocks.*)-1.

func (*ChartData) Lengthen

func (charts *ChartData) Lengthen() error

Lengthen performs data validation and populates the Days zoomSet. If there is an update to a zoomSet or windowSet, the cacheID will be incremented.

func (*ChartData) Load

func (charts *ChartData) Load(cacheDumpPath string) error

Load loads chart data from the gob file at the specified path and performs an update.

func (*ChartData) MissedVotesTip

func (charts *ChartData) MissedVotesTip() int32

MissedVotesTip is the height of the MissedVotes data.

func (*ChartData) NewAtomsTip

func (charts *ChartData) NewAtomsTip() int32

NewAtomsTip is the height of the NewAtoms data.

func (*ChartData) PoolSizeTip

func (charts *ChartData) PoolSizeTip() int32

PoolSizeTip is the height of the PoolSize data.

func (*ChartData) ReorgHandler

func (charts *ChartData) ReorgHandler(reorg *txhelpers.ReorgData) error

ReorgHandler handles the charts cache data reorganization. ReorgHandler satisfies notification.ReorgHandler, and is registered as a handler in main.go.

func (*ChartData) StateID

func (charts *ChartData) StateID() uint64

StateID returns a unique (enough) ID associated with the state of the Blocks data in a thread-safe way.

func (*ChartData) TicketPriceTip

func (charts *ChartData) TicketPriceTip() int32

TicketPriceTip is the height of the TicketPrice data.

func (*ChartData) TotalMixedTip

func (charts *ChartData) TotalMixedTip() int32

TotalMixedTip is the height of the CoinJoin Total Mixed data

func (*ChartData) TriggerUpdate

func (charts *ChartData) TriggerUpdate(_ string, _ uint32) error

TriggerUpdate triggers (*ChartData).Update.

func (*ChartData) Update

func (charts *ChartData) Update() error

Update refreshes chart data by calling the ChartUpdaters sequentially. The Update is abandoned with a warning if stateID changes while running a Fetcher (likely due to a new update starting during a query).

type ChartError

type ChartError string

ChartError is an Error interface for use with constant errors.

func (ChartError) Error

func (e ChartError) Error() string

type ChartFloats

type ChartFloats []float64

ChartFloats is a slice of floats. It satisfies the lengther interface, and provides methods for taking averages or sums of segments.

func (ChartFloats) Avg

func (data ChartFloats) Avg(s, e int) float64

Avg is the average value of a segment of the dataset.

func (ChartFloats) Length

func (data ChartFloats) Length() int

Length returns the length of data. Satisfies the lengther interface.

func (ChartFloats) Sum

func (data ChartFloats) Sum(s, e int) (sum float64)

Sum is the accumulation of a segment of the dataset.

func (ChartFloats) Truncate

func (data ChartFloats) Truncate(l int) lengther

Truncate makes a subset of the underlying dataset. It satisfies the lengther interface.

type ChartGobject

type ChartGobject struct {
	Height       ChartUints
	Time         ChartUints
	PoolSize     ChartUints
	PoolValue    ChartUints
	BlockSize    ChartUints
	TxCount      ChartUints
	NewAtoms     ChartUints
	Chainwork    ChartUints
	Fees         ChartUints
	WindowTime   ChartUints
	PowDiff      ChartFloats
	TicketPrice  ChartUints
	StakeCount   ChartUints
	MissedVotes  ChartUints
	TotalMixed   ChartUints
	AnonymitySet ChartUints
}

ChartGobject is the storage object for saving to a gob file. ChartData itself has a lot of extraneous fields, and also embeds sync.RWMutex, so is not suitable for gobbing.

type ChartMaker

type ChartMaker func(charts *ChartData, bin binLevel, axis axisType) ([]byte, error)

ChartMaker is a function that accepts a chart type and BinLevel, and returns a JSON-encoded chartResponse.

type ChartUints

type ChartUints []uint64

ChartUints is a slice of uints. It satisfies the lengther interface, and provides methods for taking averages or sums of segments.

func (ChartUints) Avg

func (data ChartUints) Avg(s, e int) uint64

Avg is the average value of a segment of the dataset.

func (ChartUints) Length

func (data ChartUints) Length() int

Length returns the length of data. Satisfies the lengther interface.

func (ChartUints) Sum

func (data ChartUints) Sum(s, e int) (sum uint64)

Sum is the accumulation of a segment of the dataset.

func (ChartUints) Truncate

func (data ChartUints) Truncate(l int) lengther

Truncate makes a subset of the underlying dataset. It satisfies the lengther interface.

type ChartUpdater

type ChartUpdater struct {
	Tag string
	// In addition to the sql.Rows and an error, the fetcher should return a
	// context.CancelFunc if appropriate, else a dummy.
	Fetcher func(*ChartData) (*sql.Rows, func(), error)
	// The Appender will be run under mutex lock.
	Appender func(*ChartData, *sql.Rows) error
}

ChartUpdater is a pair of functions for fetching and appending chart data. The two steps are divided so that ChartData can check whether another thread has updated the data during the query, and abandon an update with appropriate messaging.

type TxHistory

type TxHistory struct {
	TypeByInterval    [dbtypes.NumIntervals]*dbtypes.ChartsData
	AmtFlowByInterval [dbtypes.NumIntervals]*dbtypes.ChartsData
}

TxHistory contains ChartsData for different chart types (tx type and amount flow), each with data at known time intervals (TimeBasedGrouping).

func (*TxHistory) Clear

func (th *TxHistory) Clear()

Clear sets each *ChartsData to nil, effectively clearing the TxHistory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL