cache

package module
v2.2.4 Latest Latest
Warning

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

 Go to latest Published: Aug 19, 2019 License: ISC Imports: 15 Imported by: 6

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"
	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)

Check 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 int) *AddressCache

NewAddressCache constructs an AddressCache with capacity for the specified number of address rows.

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) Chart 

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

Chart will return a JSON-encoded chartResponse of the provided type and BinLevel.

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) 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   ChartFloats
	BlockSize   ChartUints
	TxCount     ChartUints
	NewAtoms    ChartUints
	Chainwork   ChartUints
	Fees        ChartUints
	WindowTime  ChartUints
	PowDiff     ChartFloats
	TicketPrice ChartUints
	StakeCount  ChartUints
	MissedVotes 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.