From 829a6f11c5921c9e9e1e5f7a8cd86e3953955778 Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Sat, 27 Mar 2021 14:54:21 +1000
Subject: [PATCH] Document the behaviour of the `select!` macro

---
 tower-batch/src/worker.rs                  | 1 +
 zebrad/src/components/inbound/downloads.rs | 2 ++
 zebrad/src/components/sync/downloads.rs    | 4 ++++
 zebrad/src/components/tokio.rs             | 3 +++
 4 files changed, 10 insertions(+)

diff --git a/tower-batch/src/worker.rs b/tower-batch/src/worker.rs
index 4137dfed..6fc58e3c 100644
--- a/tower-batch/src/worker.rs
+++ b/tower-batch/src/worker.rs
@@ -143,6 +143,7 @@ where
                 },
                 Some(mut sleep) => {
                     // Wait on either a new message or the batch timer.
+                    // If both are ready, select! chooses one of them at random.
                     tokio::select! {
                         maybe_msg = self.rx.recv() => match maybe_msg {
                             Some(msg) => {
diff --git a/zebrad/src/components/inbound/downloads.rs b/zebrad/src/components/inbound/downloads.rs
index 8492ae90..54e2bc90 100644
--- a/zebrad/src/components/inbound/downloads.rs
+++ b/zebrad/src/components/inbound/downloads.rs
@@ -223,6 +223,8 @@ where
         .in_current_span();
 
         let task = tokio::spawn(async move {
+            // TODO: if the verifier and cancel are both ready, which should we
+            //       prefer? (Currently, select! chooses one at random.)
             tokio::select! {
                 _ = &mut cancel_rx => {
                     tracing::trace!("task cancelled prior to completion");
diff --git a/zebrad/src/components/sync/downloads.rs b/zebrad/src/components/sync/downloads.rs
index 0751f42a..01f81817 100644
--- a/zebrad/src/components/sync/downloads.rs
+++ b/zebrad/src/components/sync/downloads.rs
@@ -149,6 +149,8 @@ where
         let mut verifier = self.verifier.clone();
         let task = tokio::spawn(
             async move {
+                // TODO: if the verifier and cancel are both ready, which should
+                //       we prefer? (Currently, select! chooses one at random.)
                 let rsp = tokio::select! {
                     _ = &mut cancel_rx => {
                         tracing::trace!("task cancelled prior to download completion");
@@ -169,6 +171,8 @@ where
                 metrics::counter!("sync.downloaded.block.count", 1);
 
                 let rsp = verifier.ready_and().await?.call(block);
+                // TODO: if the verifier and cancel are both ready, which should
+                //       we prefer? (Currently, select! chooses one at random.)
                 let verification = tokio::select! {
                     _ = &mut cancel_rx => {
                         tracing::trace!("task cancelled prior to verification");
diff --git a/zebrad/src/components/tokio.rs b/zebrad/src/components/tokio.rs
index 1f39d5ca..49c13c56 100644
--- a/zebrad/src/components/tokio.rs
+++ b/zebrad/src/components/tokio.rs
@@ -46,6 +46,8 @@ pub(crate) trait RuntimeRun {
 impl RuntimeRun for Runtime {
     fn run(&mut self, fut: impl Future<Output = Result<(), Report>>) {
         let result = self.block_on(async move {
+            // If the run task and shutdown are both ready, select! chooses
+            // one of them at random.
             tokio::select! {
                 result = fut => result,
                 _ = shutdown() => Ok(()),
@@ -68,6 +70,7 @@ mod imp {
     use tracing::info;
 
     pub(super) async fn shutdown() {
+        // If both signals are received, select! chooses one of them at random.
         tokio::select! {
             // SIGINT  - Terminal interrupt signal. Typically generated by shells in response to Ctrl-C.
             () = sig(SignalKind::interrupt(), "SIGINT") => {}