Document the behaviour of the `select!` macro

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) => {

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");

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");

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") => {}