From a5b2e7786e3196ad17b319e131a9f6b4df79b70d Mon Sep 17 00:00:00 2001 From: Wei Tang <wei@that.world> Date: Tue, 11 May 2021 13:25:50 +0200 Subject: [PATCH] pow: fix docs on mining worker (#8759) * pow: fix docs on mining worker * typo: miner -> mining * Switch to proper Rust intra-doc link --- substrate/client/consensus/pow/README.md | 12 ++++++++++-- substrate/client/consensus/pow/src/lib.rs | 16 ++++++++++++---- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/substrate/client/consensus/pow/README.md b/substrate/client/consensus/pow/README.md index a335ec36704..8dba30fc5a3 100644 --- a/substrate/client/consensus/pow/README.md +++ b/substrate/client/consensus/pow/README.md @@ -3,7 +3,15 @@ Proof of work consensus for Substrate. To use this engine, you can need to have a struct that implements `PowAlgorithm`. After that, pass an instance of the struct, along with other necessary client references to `import_queue` to setup -the queue. Use the `start_mine` function for basic CPU mining. +the queue. + +This library also comes with an async mining worker, which can be +started via the `start_mining_worker` function. It returns a worker +handle together with a future. The future must be pulled. Through +the worker handle, you can pull the metadata needed to start the +mining process via `MiningWorker::metadata`, and then do the actual +mining on a standalone thread. Finally, when a seal is found, call +`MiningWorker::submit` to build the block. The auxiliary storage for PoW engine only stores the total difficulty. For other storage requirements for particular PoW algorithm (such as @@ -13,4 +21,4 @@ for the auxiliary storage. It is also possible to just use the runtime as the storage, but it is not recommended as it won't work well with light clients. -License: GPL-3.0-or-later WITH Classpath-exception-2.0 \ No newline at end of file +License: GPL-3.0-or-later WITH Classpath-exception-2.0 diff --git a/substrate/client/consensus/pow/src/lib.rs b/substrate/client/consensus/pow/src/lib.rs index b12bad7bac2..17cdae48cdb 100644 --- a/substrate/client/consensus/pow/src/lib.rs +++ b/substrate/client/consensus/pow/src/lib.rs @@ -19,14 +19,22 @@ //! Proof of work consensus for Substrate. //! //! To use this engine, you can need to have a struct that implements -//! `PowAlgorithm`. After that, pass an instance of the struct, along -//! with other necessary client references to `import_queue` to setup -//! the queue. Use the `start_mine` function for basic CPU mining. +//! [`PowAlgorithm`]. After that, pass an instance of the struct, along +//! with other necessary client references to [`import_queue`] to setup +//! the queue. +//! +//! This library also comes with an async mining worker, which can be +//! started via the [`start_mining_worker`] function. It returns a worker +//! handle together with a future. The future must be pulled. Through +//! the worker handle, you can pull the metadata needed to start the +//! mining process via [`MiningWorker::metadata`], and then do the actual +//! mining on a standalone thread. Finally, when a seal is found, call +//! [`MiningWorker::submit`] to build the block. //! //! The auxiliary storage for PoW engine only stores the total difficulty. //! For other storage requirements for particular PoW algorithm (such as //! the actual difficulty for each particular blocks), you can take a client -//! reference in your `PowAlgorithm` implementation, and use a separate prefix +//! reference in your [`PowAlgorithm`] implementation, and use a separate prefix //! for the auxiliary storage. It is also possible to just use the runtime //! as the storage, but it is not recommended as it won't work well with light //! clients. -- GitLab