From e8579a9268dd33e983c42b96bf83799dab660f72 Mon Sep 17 00:00:00 2001
From: Harper Andrews <10224994+ItsHarper@users.noreply.github.com>
Date: Fri, 8 Aug 2025 18:39:44 -0500
Subject: [PATCH] Add examples for receiving data from a job (#16372)

# Description

The existing examples cover how to send data to a job, but I think it
will be much more common to want to receive data from a job.

# User-Facing Changes

Just documentation, though it may be worth highlighting anyway. I really
thought for a while that this was not possible yet. See also my book PR
https://github.com/nushell/nushell.github.io/pull/2006 (`job send` and
`job recv` were not documented in the book at all).
---
 .../nu-command/src/experimental/job_recv.rs   |  7 ++++++-
 .../nu-command/src/experimental/job_send.rs   | 19 +++++++++++++------
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/crates/nu-command/src/experimental/job_recv.rs b/crates/nu-command/src/experimental/job_recv.rs
index c98d7a1783..a3a250b275 100644
--- a/crates/nu-command/src/experimental/job_recv.rs
+++ b/crates/nu-command/src/experimental/job_recv.rs
@@ -32,7 +32,7 @@ Messages may have numeric flags attached to them. This commands supports filteri
 If no tag is specified, this command will accept any message.
 
 If no message with the specified tag (if any) is available in the mailbox, this command will block the current thread until one arrives.
-By default this command block indefinitely until a matching message arrives, but a timeout duration can be specified. 
+By default this command block indefinitely until a matching message arrives, but a timeout duration can be specified.
 If a timeout duration of zero is specified, it will succeed only if there already is a message in the mailbox.
 
 Note: When using par-each, only one thread at a time can utilize this command.
@@ -116,6 +116,11 @@ in no particular order, regardless of the specified timeout parameter.
                 description: "Get a message or fail if no message is available immediately",
                 result: None,
             },
+            Example {
+                example: "job spawn { sleep 1sec; 'hi' | job send 0 }; job recv",
+                description: "Receive a message from a newly-spawned job",
+                result: None,
+            },
         ]
     }
 }
diff --git a/crates/nu-command/src/experimental/job_send.rs b/crates/nu-command/src/experimental/job_send.rs
index 868c0ed42c..3450111145 100644
--- a/crates/nu-command/src/experimental/job_send.rs
+++ b/crates/nu-command/src/experimental/job_send.rs
@@ -17,7 +17,7 @@ impl Command for JobSend {
         r#"
 This command sends a message to a background job, which can then read sent messages
 in a first-in-first-out fashion with `job recv`. When it does so, it may additionally specify a numeric filter tag,
-in which case it will only read messages sent with the exact same filter tag. 
+in which case it will only read messages sent with the exact same filter tag.
 In particular, the id 0 refers to the main/initial nushell thread.
 
 A message can be any nushell value, and streams are always collected before being sent.
@@ -101,10 +101,17 @@ This command never blocks.
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            example: "let id = job spawn { job recv | save sent.txt }; 'hi' | job send $id",
-            description: "Send a message to a newly spawned job",
-            result: None,
-        }]
+        vec![
+            Example {
+                example: "let id = job spawn { job recv | save sent.txt }; 'hi' | job send $id",
+                description: "Send a message from the main thread to a newly-spawned job",
+                result: None,
+            },
+            Example {
+                example: "job spawn { sleep 1sec; 'hi' | job send 0 }; job recv",
+                description: "Send a message from a newly-spawned job to the main thread (which always has an ID of 0)",
+                result: None,
+            },
+        ]
     }
 }