Merge pull request #24718 from JuliaLang/kf/deprw

Deprecate `readandwrite` and add docs for `Pipe`

base/deprecated.jl

@@ -2801,6 +2801,21 @@ function Filesystem.tempname(uunique::UInt32)
 end
 end
 
+"""
+    readandwrite(command)
+
+Starts running a command asynchronously, and returns a tuple (stdout,stdin,process) of the
+output stream and input stream of the process, and the process object itself.
+"""
+function readandwrite(cmds::AbstractCmd)
+    depwarn("""`readandwrite(::Cmd)` is deprecated in favor of `open(::Cmd, \"r+\").
+               You may read/write the returned process object for access to stdio.""",
+            :readandwrite)
+    processes = open(cmds, "r+")
+    return (processes.out, processes.in, processes)
+end
+export readandwrite
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/exports.jl

@@ -1072,7 +1072,6 @@ export
     kill,
     process_exited,
     process_running,
-    readandwrite,
     run,
     setenv,
     spawn,

base/libgit2/gitcredential.jl

@@ -168,17 +168,16 @@ end
 
 function run!(helper::GitCredentialHelper, operation::AbstractString, cred::GitCredential)
     cmd = `$(helper.cmd) $operation`
-    output, input, p = readandwrite(cmd)
+    p = open(cmd, "r+")
 
     # Provide the helper with the credential information we know
-    write(input, cred)
-    write(input, "\n")
-    t = @async close(input)
+    write(p, cred)
+    write(p, "\n")
+    t = @async close(p.in)
 
     # Process the response from the helper
-    Base.read!(output, cred)
-    close(output)
-    wait(t)
+    Base.read!(p, cred)
+    wait(p)
 
     return cred
 end

base/process.jl

@@ -636,19 +636,6 @@ function open(f::Function, cmds::AbstractCmd, args...)
     return ret
 end
 
-# TODO: deprecate this
-
-"""
-    readandwrite(command)
-
-Starts running a command asynchronously, and returns a tuple (stdout,stdin,process) of the
-output stream and input stream of the process, and the process object itself.
-"""
-function readandwrite(cmds::AbstractCmd)
-    processes = open(cmds, "r+")
-    return (processes.out, processes.in, processes)
-end
-
 function read(cmd::AbstractCmd)
     procs = open(cmd, "r", DevNull)
     bytes = read(procs.out)

base/stream.jl

@@ -574,6 +574,22 @@ mutable struct Pipe <: AbstractPipe
     in::PipeEndpoint # writable
     out::PipeEndpoint # readable
 end
+
+"""
+Construct an uninitialized Pipe object.
+
+The appropriate end of the pipe will be automatically initialized if
+the object is used in process spawning. This can be useful to easily
+obtain references in process pipelines, e.g.:
+
+```
+julia> err = Pipe()
+
+# After this `err` will be initialized and you may read `foo`'s
+# stderr from the `err` pipe.
+julia> spawn(pipeline(pipeline(`foo`, stderr=err), `cat`))
+```
+"""
 Pipe() = Pipe(PipeEndpoint(), PipeEndpoint())
 pipe_reader(p::Pipe) = p.out
 pipe_writer(p::Pipe) = p.in

test/repl.jl

@@ -669,9 +669,9 @@ let exename = Base.julia_cmd()
     end
 
     # Test stream mode
-    outs, ins, p = readandwrite(`$exename --startup-file=no -q`)
-    write(ins, "1\nquit()\n")
-    @test read(outs, String) == "1\n"
+    p = open(`$exename --startup-file=no -q`, "r+")
+    write(p, "1\nquit()\n")
+    @test read(p, String) == "1\n"
 end # let exename
 
 # issue #19864:

test/spawn.jl

@@ -138,16 +138,16 @@ let pathA = readchomp(setenv(`$shcmd -c "pwd -P"`;dir="..")),
     end
 end
 
-let str = "", stdin, stdout, proc, str2, file
+let str = "", proc, str2, file
     for i = 1:1000
       str = "$str\n $(randstring(10))"
     end
 
     # Here we test that if we close a stream with pending writes, we don't lose the writes.
-    stdout, stdin, proc = readandwrite(`$catcmd -`)
-    write(stdin, str)
-    close(stdin)
-    str2 = read(stdout, String)
+    proc = open(`$catcmd -`, "r+")
+    write(proc, str)
+    close(proc.in)
+    str2 = read(proc, String)
     @test str2 == str
 
     # This test hangs if the end-of-run-walk-across-uv-streams calls shutdown on a stream that is shutting down.