cpuminer

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 New(cfg *Config) *CPUMiner
  • 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

Variables

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

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

Types

type CPUMiner

type CPUMiner struct {
	sync.Mutex
	// contains filtered or unexported fields
}

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 GenerateNBlocks, that generates a specific number of blocks that extend the main chain.

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

func New(cfg *Config) *CPUMiner

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 GenerateNBlocks to mine a discrete number of blocks.

See the documentation for CPUMiner type for more details.

func (*CPUMiner) GenerateNBlocks

func (m *CPUMiner) GenerateNBlocks(ctx context.Context, n uint32) ([]*chainhash.Hash, error)

GenerateNBlocks generates the requested number of blocks in the discrete mining mode and returns a list of the hashes of generated blocks that were added to the main chain.

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.

Note that, as the above implies, this will only consider blocks successfully added to the main chain in the overall count, so, upon returning, the list of hashes will only contain the hashes of those blocks. This distinction is important because it is sometimes possible for a block to be rejected or be added to a side chain if it happens to be solved around the same time another one shows up.

func (*CPUMiner) HashesPerSecond

func (m *CPUMiner) HashesPerSecond() float64

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

func (m *CPUMiner) IsMining() bool

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

func (m *CPUMiner) NumWorkers() int32

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

func (m *CPUMiner) Run(ctx context.Context)

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

func (m *CPUMiner) SetNumWorkers(numWorkers int32)

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

	// MiningAddrs is a list of payment addresses to use for the generated
	// blocks.  Each generated block will randomly choose one of them.
	MiningAddrs []vclutil.Address

	// 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(*vclutil.Block, blockchain.BehaviorFlags) (bool, 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
}

Config is a descriptor containing the CPU miner configuration.