README
¶
cpuminer
Package cpuminer provides facilities for solving blocks (mining) using the CPU.
Overview
This package is currently a work in progress. It works without issue since it is used in several of the integration tests, but the API is not really ready for public consumption as it has simply been refactored out of the main codebase for now.
License
Package cpuminer is licensed under the copyfree ISC License.
Documentation
¶
Overview ¶
Package cpuminer provides facilities for solving blocks (mining) using the CPU.
Index ¶
- Variables
- func UseLogger(logger slog.Logger)
- type CPUMiner
- func (m *CPUMiner) BlockConnected(block *dcrutil.Block)
- func (m *CPUMiner) GenerateNBlocks(ctx context.Context, n uint32) ([]chainhash.Hash, error)
- func (m *CPUMiner) HashesPerSecond() float64
- func (m *CPUMiner) IsMining() bool
- func (m *CPUMiner) NumWorkers() int32
- func (m *CPUMiner) Run(ctx context.Context)
- func (m *CPUMiner) SetNumWorkers(numWorkers int32)
- type Config
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCancelDiscreteMining indicates the discrete mining process was // cancelled before completing successfully. For example, this can happen // when explicitly requested via calling [CPUMiner.GenerateNBlocks] with 0 // or when the parent context is cancelled. ErrCancelDiscreteMining = errors.New("discrete mining process canceled") )
var ( // MaxNumWorkers is the maximum number of workers that will be allowed for // mining and is based on the number of processor cores. This helps ensure // system stays reasonably responsive under heavy load. MaxNumWorkers = uint32(runtime.NumCPU() * 2) )
Functions ¶
Types ¶
type CPUMiner ¶
CPUMiner provides facilities for solving blocks (mining) using the CPU in a concurrency-safe manner. It consists of two main modes -- a normal mining mode that tries to solve blocks continuously and a discrete mining mode, which is accessible via CPUMiner.GenerateNBlocks, that mines blocks on an as needed basis to extend the main chain by a specific number of blocks.
The normal mining mode consists of two main goroutines -- a speed monitor and a controller for additional worker goroutines that generate and solve blocks.
When the CPU miner is first started via the Run method, it will not have any workers which means it will be idle. The number of worker goroutines for the normal mining mode can be set via the SetNumWorkers method.
func New ¶
New returns a new instance of a CPU miner for the provided configuration options.
Use Run to initialize the CPU miner and then either use SetNumWorkers with a non-zero value to start the normal continuous mining mode or use CPUMiner.GenerateNBlocks to mine a discrete number of blocks.
See the documentation for CPUMiner type for more details.
func (*CPUMiner) BlockConnected ¶ added in v1.10.0
BlockConnected informs the CPU miner that a block has been connected to the main chain. It is the caller's responsibility to ensure this is only invoked as described.
This function is safe for concurrent access.
func (*CPUMiner) GenerateNBlocks ¶
GenerateNBlocks generates blocks on an as needed basis to extend the main chain by the requested number of blocks in the discrete mining mode and returns a list of hashes of the blocks that ultimately extended the main chain, regardless of their origin.
The aforementioned distinction regarding the origin of the returned hashes is important to note because the blocks that ultimately extend the main chain may be different from the blocks generated since blocks from other sources may arrive while the discrete mining process is underway leading to generation of more or less blocks than the target number.
A best effort attempt is made to avoid as many forks as possible by discarding any locally-mined blocks that would knowingly cause a fork with blocks that arrive from other sources and to only generate as many blocks as are necessary to achieve extending the main chain by the specified number of blocks. However, forks may still occur since it is not always possible to detect forks beforehand. Nevertheless, any such forks will not count towards the requested number of blocks since they do not extend the main chain.
Only one instance of discrete mining may be active at once. An active discrete mining instance may be canceled by specifying 0 for the number of blocks. A canceled instance will return ErrCancelDiscreteMining.
Specifying 0 for the number of blocks when there are no active discrete mining instances has no effect.
An error will be returned when either normal mining is active or when a discrete mining instance is already active and the specified number of blocks is not 0.
It makes use of a subscription to the background block template generator to obtain the templates and attempts to solve them while automatically switching to new templates as they become available as needed. As a result, it supports many of the nice features of the template subscriptions such as giving all votes a chance to arrive and automatically switching to templates building on new blocks that arrive from other sources.
func (*CPUMiner) HashesPerSecond ¶
HashesPerSecond returns the number of hashes per second the normal mode mining process is performing. 0 is returned if the miner is not currently mining anything in normal mining mode.
This function is safe for concurrent access.
func (*CPUMiner) IsMining ¶
IsMining returns whether or not the CPU miner is currently mining in either the normal or discrete mining modes.
This function is safe for concurrent access.
func (*CPUMiner) NumWorkers ¶
NumWorkers returns the number of workers which are running to solve blocks in the normal mining mode.
This function is safe for concurrent access.
func (*CPUMiner) Run ¶
Run starts the CPU miner with zero workers which means it will be idle. It blocks until the provided context is cancelled.
Use the SetNumWorkers method to start solving blocks in the normal mining mode.
func (*CPUMiner) SetNumWorkers ¶
SetNumWorkers sets the number of workers to create for solving blocks in the normal mining mode. Negative values cause the default number of workers to be used, values larger than the max allowed are limited to the max, and a value of 0 causes all normal mode CPU mining to be stopped.
NOTE: This will have no effect if discrete mining mode is currently active via CPUMiner.GenerateNBlocks.
This function is safe for concurrent access.
type Config ¶
type Config struct {
// ChainParams identifies which chain parameters the CPU miner is
// associated with.
ChainParams *chaincfg.Params
// PermitConnectionlessMining allows single node mining.
PermitConnectionlessMining bool
// BgBlkTmplGenerator identifies the instance to use in order to
// generate block templates that the miner will attempt to solve.
BgBlkTmplGenerator *mining.BgBlkTmplGenerator
// BestSnapshot defines the function to use to access information about the
// current best block. The returned instance should be treated as immutable.
BestSnapshot func() *blockchain.BestState
// BlockHashByHeight returns the hash of the block at the given height in
// the main chain.
BlockHashByHeight func(height int64) (*chainhash.Hash, error)
// ProcessBlock defines the function to call with any solved blocks.
// It typically must run the provided block through the same set of
// rules and handling as any other block coming from the network.
ProcessBlock func(*dcrutil.Block) error
// ConnectedCount defines the function to use to obtain how many other
// peers the server is connected to. This is used by the automatic
// persistent mining routine to determine whether or it should attempt
// mining. This is useful because there is no point in mining when not
// connected to any peers since there would no be anyone to send any
// found blocks to.
ConnectedCount func() int32
// IsCurrent defines the function to use to obtain whether or not the
// block chain is current. This is used by the automatic persistent
// mining routine to determine whether or it should attempt mining.
// This is useful because there is no point in mining if the chain is
// not current since any solved blocks would be on a side chain and
// up orphaned anyways.
IsCurrent func() bool
// IsBlake3PowAgendaActive returns whether or not the agenda to change the
// proof of work hash function to blake3, as defined in DCP0011, has passed
// and is now active for the block AFTER the given block.
IsBlake3PowAgendaActive func(prevHash *chainhash.Hash) (bool, error)
}
Config is a descriptor containing the CPU miner configuration.
Source Files