Move description of the Rust flavor of stages to service.rs

src/fullnode.md

@@ -27,21 +27,3 @@ hardware being pipelined is the same, the network input, the GPU cards, the CPU
 cores, and the network output.  What it does with that hardware is different.
 The Tpu exists to create ledger entries whereas the Tvu exists to validate
 them.
-
-## Pipeline stages in Rust
-
-To approach to creating a pipeline stage in Rust may be unique to Solana. We
-haven't seen the same technique used in other Rust projects and there may be
-better ways to do it. The Solana approach defines a stage as an object that
-communicates to its previous stage and the next stage using channels. By
-convention, each stage accepts a *receiver* for input and creates a second
-output channel. The second channel is used to pass data to the next stage, and
-so its sender is moved into the stage's thread and the receiver is returned
-from its constructor.
-
-A well-written stage should create a thread and call a short `run()` method.
-The method should read input from its input channel, call a function from
-another module that processes it, and then send the output to the output
-channel. The functionality in the second module will likely not use threads or
-channels.
-

src/service.rs

@@ -1,3 +1,26 @@
+//! The `service` module implements a trait used by services and stages.
+//!
+//! A Service is any object that implements its functionality on a separate thread. It implements a
+//! `join()` method, which can be used to wait for that thread to close.
+//!
+//! The Service trait may also be used to implement a pipeline stage. Like a service, its
+//! functionality is also implemented by a thread, but unlike a service, a stage isn't a server
+//! that replies to client requests. Instead, a stage acts more like a pure function. It's a oneway
+//! street. It processes messages from its input channel and then sends the processed data to an
+//! output channel. Stages can be composed to form a linear chain called a pipeline.
+//!
+//! The approach to creating a pipeline stage in Rust may be unique to Solana. We haven't seen the
+//! same technique used in other Rust projects and there may be better ways to do it. The Solana
+//! approach defines a stage as an object that communicates to its previous stage and the next
+//! stage using channels. By convention, each stage accepts a *receiver* for input and creates a
+//! second output channel. The second channel is used to pass data to the next stage, and so its
+//! sender is moved into the stage's thread and the receiver is returned from its constructor.
+//!
+//! A well-written stage should create a thread and call a short `run()` method.  The method should
+//! read input from its input channel, call a function from another module that processes it, and
+//! then send the output to the output channel. The functionality in the second module will likely
+//! not use threads or channels.
+
 use std::thread::Result;
 
 pub trait Service {