pg: canonical usage doctest on the module

A plain-actor example showing the one thing process groups are for: a live
membership view that self-heals on death. Two workers join a group; one dies
and is evicted by the death hook with no deregistration call; one leaves
voluntarily. Runs under cargo test --doc.

(Deliberately not a worker-pool-with-dispatch example: pg is membership and
liveness, not a message router — routing a job to a picked pid needs a
pid->handle map that pg does not provide, so a dispatch example would document
the adapter, not pg.)

src/pg.rs

@@ -6,6 +6,41 @@
 //! generalization of the bimap; it is its own keyspace sharing only the
 //! liveness signal source (monitors) and the lock *class*.
 //!
+//! ## Example
+//!
+//! A group is a live membership view: members join, and a member that dies is
+//! evicted automatically — no deregistration call, no bookkeeping.
+//!
+//! ```
+//! use smarm::{channel, join, leave, members, pick, run, spawn};
+//!
+//! run(|| {
+//!     let (tx1, rx1) = channel::<()>();
+//!     let (tx2, rx2) = channel::<()>();
+//!     let w1 = spawn(move || { rx1.recv().unwrap(); });
+//!     let w2 = spawn(move || { rx2.recv().unwrap(); });
+//!
+//!     // Workers join the group; `members` is the live view of it.
+//!     join("pool", w1.pid());
+//!     join("pool", w2.pid());
+//!     assert_eq!(members("pool").len(), 2);
+//!
+//!     // One worker dies. Nobody told the group — the death hook evicts it,
+//!     // so it is gone from `members` and never returned by `pick`.
+//!     tx1.send(()).unwrap();
+//!     w1.join().unwrap();
+//!     assert_eq!(members("pool"), vec![w2.pid()]);
+//!     assert_eq!(pick("pool"), Some(w2.pid()));
+//!
+//!     // Voluntary departure works too.
+//!     leave("pool", w2.pid());
+//!     assert!(pick("pool").is_none());
+//!
+//!     tx2.send(()).unwrap();
+//!     w2.join().unwrap();
+//! });
+//! ```
+//!
 //! ## Cleanup is eager and monitor-driven (unlike the registry)
 //!
 //! The registry prunes a stale binding lazily, on contact, because it only