Documents `From` implementations for `Stdio` by octronics · Pull Request #55200 · rust-lang/rust

octronics · 2018-10-19T10:55:34Z

This PR solves part of #51430 by adding a basic summary and an example to each impl From inside process module (ChildStdin, ChildStdout, ChildStderr, File).

It does not document if the conversions allocate memory and how expensive they are.

rust-highfive · 2018-10-19T10:55:37Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @kennytm (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

kennytm · 2018-10-19T11:49:50Z

Thanks for the PR! I think the documentation should better illustrate what you could do with the converted Stdio instance, e.g.

 fs::write("foo.txt",b"Hello, world!")?;let file = File::open("foo.txt")?;let output = Command::new("rev").stdin(Stdio::from(file))// convert the File into a Stdio.output()?;assert_eq!(output.stdout,b"!dlrow ,olleH");

Note that our examples only used echo and rev as examples since /bin/ls should not exist on Windows.

octronics · 2018-10-19T12:16:00Z

Is ? working on documentation code blocks?

octronics · 2018-10-19T12:37:06Z

Is something like the following will be OK for the other examples?

use std::process::{Command,Stdio};let hello = Command::new("echo").arg("Hello, world!").stdout(Stdio::piped()).spawn().expect("failed echo command");let reverse = Command::new("rev").stdin(Stdio::from(hello.stdout.unwrap()))// convert the standard input into a Stdio.output().expect("failed reverse command");assert_eq!(reverse.stdout,b"!dlrow ,olleH\n");

This work without the explicit Stdio::from conversion too.

rust-highfive · 2018-10-19T13:34:01Z

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[00:48:10] .................................................................................................... 2200/4630
[00:48:15] ................................i................................................................... 2300/4630
[00:48:18] .................................................................................................... 2400/4630
[00:48:22] .................................................................................................... 2500/4630
[00:48:25] ..............................................iiiiiiiii............................................. 2600/4630
[00:48:31] .................................................................................................... 2800/4630
[00:48:35] .................................................................................................... 2900/4630
[00:48:38] ...........................................................................i........................ 3000/4630
[00:48:40] .................................................................................................... 3100/4630
---
travis_time:start:test_codegen
Check compiletest suite=codegen mode=codegen (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:00:55] [01:00:55] running 111 tests
[01:00:58] i..ii...iii.......i....i........i..iii...........i.....i.....ii...i.i.ii..............i...ii..ii.i.. 100/111
[01:00:58] ..iiii.....
[01:00:58] [01:00:58] finished in 3.330
[01:00:58] travis_fold:end:test_codegen
---
[01:19:07] .................................................................................................... 400/959
[01:19:18] ...................................iiii........ii................................................... 500/959
[01:19:23] .................................................................................................... 600/959
[01:19:33] ...................................................................................iiii............. 700/959
[01:19:47] ....................................................F............................................... 800/959
[01:20:00] ........iiii...............................................
[01:20:00] failures:
[01:20:00] [01:20:00] ---- process.rs - process::Stdio::from (line 1086) stdout ----
[01:20:00] ---- process.rs - process::Stdio::from (line 1086) stdout ----
[01:20:00] thread 'process.rs - process::Stdio::from (line 1086)' panicked at 'test executable failed:
[01:20:00] thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 30, kind: Other, message: "Read-only file system" }', libcore/result.rs:1009:5
[01:20:00] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[01:20:00] [01:20:00] ', librustdoc/test.rs:367:17
---
[01:20:00] [01:20:00] error: test failed, to rerun pass '--doc'
[01:20:00] [01:20:00] [01:20:00] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind jemalloc backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-p" "std" "--" "--quiet"
[01:20:00] [01:20:00] [01:20:00] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:20:00] Build completed unsuccessfully in 0:36:20
[01:20:00] Build completed unsuccessfully in 0:36:20
[01:20:00] Makefile:58: recipe for target 'check' failed
[01:20:00] make: *** [check] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:18496908
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
---
travis_time:end:17600cc3:start=1539956037532587825,finish=1539956037536521195,duration=3933370
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:014842d0
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:07892790
travis_time:start:07892790
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:067c6e7f
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

kennytm · 2018-10-19T13:45:54Z

@octronics That looks fine.

Doc code blocks doesn't implicitly support ? yet, but you could use # to hide some lines, like this:

/// ```rust/// use std::fs::File;////// # fn main() -> std::io::Result<()> {/// let f = File::open("src/lib.rs")?;/// # Ok(()) }/// ```

octronics · 2018-10-19T14:21:10Z

Build failure is caused by read-only filesystems on CI. So will add no_run on code blocks if we stick with it.

The .stdin() function works without explicit conversion, I don't think it is good as conversion examples.
What do you think about?

fnwork_with_stdio(io:Stdio){}
var file = File::open("foo.txt").unwrap();work_with_stdio(Stdio::from(file));

Any idea about code that will need explicit conversion?

kennytm · 2018-10-19T14:29:45Z

@octronics The main purpose of the Stdio structure is to be passed into stdin(), stdout() and stderr() methods, so I don't think it's a good idea to create an artificial work_with_stdio(). And it is probably a good thing that we show the idiomatic, "implicit" conversion example

let file = File::open("foo.txt")?;let output = Command::new("rev").stdin(file).output()?;

and add a paragraph before the example explaining that Stdio::from is used here to convert the File into a Stdio.

octronics · 2018-10-19T14:33:06Z

Will do that. Thanks.

octronics · 2018-10-19T16:37:39Z

Is cat available on windows? I would us it on example for Stdio::from(ChildStderr) conversion:

use std::process::{Command,Stdio};let reverse = Command::new("rev").arg("non_existing_file.txt").stderr(Stdio::piped()).spawn().expect("failed reverse command");let cat = Command::new("cat").arg("-").stdin(reverse.stderr.unwrap())// Converted into a Stdio here.output().expect("failed echo command");assert_eq!(String::from_utf8_lossy(&cat.stdout),"rev: cannot open non_existing_file.txt: No such file or directory\n");

If it is not available, I will declare the code block as no_run.

kennytm · 2018-10-19T17:02:00Z

@oconnor663 No, but you could just feed it into another rev 🙃

The error message from Windows is likely different though. Perhaps just remove the assert_eq!.

octronics · 2018-10-19T17:08:10Z

What do you think declaring the code blocks as no_run instead?

rust-highfive · 2018-10-19T18:38:14Z

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[00:49:30] .................................................................................................... 2200/4635
[00:49:34] ....................................i............................................................... 2300/4635
[00:49:37] .................................................................................................... 2400/4635
[00:49:41] .................................................................................................... 2500/4635
[00:49:45] ..................................................iiiiiiiii......................................... 2600/4635
[00:49:51] .................................................................................................... 2800/4635
[00:49:55] .................................................................................................... 2900/4635
[00:49:58] ................................................................................i................... 3000/4635
[00:50:01] .................................................................................................... 3100/4635
---
travis_time:start:test_codegen
Check compiletest suite=codegen mode=codegen (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:02:41] [01:02:41] running 111 tests
[01:02:44] i..ii...iii.......i...i.........i..iii...........i.....i.....ii...i.i.ii..............i....ii.ii.i.. 100/111
[01:02:44] ..iiii.....
[01:02:44] [01:02:44] finished in 3.463
[01:02:44] travis_fold:end:test_codegen
---
[01:21:43] .................................................................................................... 400/961
[01:21:54] .....................................iiii........ii................................................. 500/961
[01:22:00] .................................................................................................... 600/961
[01:22:11] .....................................................................................iiii........... 700/961
[01:22:25] .......................................F...F........................................................ 800/961
[01:22:39] ..........iiii...............................................
[01:22:39] failures:
[01:22:39] [01:22:39] ---- process.rs - process::Stdio::from (line 1054) stdout ----
[01:22:39] ---- process.rs - process::Stdio::from (line 1054) stdout ----
[01:22:39] error[E0433]: failed to resolve. Use of undeclared type or module `Stdio`
[01:22:39] --> process.rs:1059:13
[01:22:39] |
[01:22:39] 8 | .stdout(Stdio::piped())
[01:22:39] | ^^^^^ Use of undeclared type or module `Stdio`
[01:22:39] [01:22:39] thread 'process.rs - process::Stdio::from (line 1054)' panicked at 'couldn't compile the test', librustdoc/test.rs:332:13
[01:22:39] [01:22:39] ---- process.rs - process::Stdio::from (line 1114) stdout ----
[01:22:39] ---- process.rs - process::Stdio::from (line 1114) stdout ----
[01:22:39] error: expected one of `.`, `;`, `?`, or an operator, found `assert_eq`
[01:22:39] |
[01:22:39] 12 | .output()?
[01:22:39] 12 | .output()?
[01:22:39] | - expected one of `.`, `;`, `?`, or an operator here
[01:22:39] 13 | [01:22:39] 14 | assert_eq!(reverse.stdout, b"!dlrow ,olleH");
[01:22:39] | ^^^^^^^^^ unexpected token
[01:22:39] error: unused import: `std::process::Command`
[01:22:39] --> process.rs:1116:5
[01:22:39] |
[01:22:39] 5 | use std::process::Command;
---
[01:22:39] 1 | #![deny(warnings)]
[01:22:39] | ^^^^^^^^
[01:22:39] = note: #[deny(unused_imports)] implied by #[deny(warnings)]
[01:22:39] [01:22:39] thread 'process.rs - process::Stdio::from (line 1114)' panicked at 'couldn't compile the test', librustdoc/test.rs:332:13
[01:22:39] [01:22:39] failures:
[01:22:39] process.rs - process::Stdio::from (line 1054)
[01:22:39] process.rs - process::Stdio::from (line 1114)
[01:22:39] process.rs - process::Stdio::from (line 1114)
[01:22:39] [01:22:39] test result: FAILED. 935 passed; 2 failed; 24 ignored; 0 measured; 0 filtered out
[01:22:39] [01:22:39] error: test failed, to rerun pass '--doc'
[01:22:39] [01:22:39] [01:22:39] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind jemalloc backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-p" "std" "--" "--quiet"
[01:22:39] [01:22:39] [01:22:39] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:22:39] Build completed unsuccessfully in 0:37:51
[01:22:39] Build completed unsuccessfully in 0:37:51
[01:22:39] make: *** [check] Error 1
[01:22:39] Makefile:58: recipe for target 'check' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:031cf3db
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
---
travis_time:end:37ef1f00:start=1539974290771851504,finish=1539974290777398890,duration=5547386
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:00fbf3fb
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

rust-highfive · 2018-10-19T20:03:09Z

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[00:48:34] .................................................................................................... 2200/4635
[00:48:38] ....................................i............................................................... 2300/4635
[00:48:41] .................................................................................................... 2400/4635
[00:48:45] .................................................................................................... 2500/4635
[00:48:48] ..................................................iiiiiiiii......................................... 2600/4635
[00:48:55] .................................................................................................... 2800/4635
[00:48:58] .................................................................................................... 2900/4635
[00:49:01] ................................................................................i................... 3000/4635
[00:49:04] .................................................................................................... 3100/4635
---
travis_time:start:test_codegen
Check compiletest suite=codegen mode=codegen (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:01:20] [01:01:20] running 111 tests
[01:01:22] i..ii...iii.......i...i.........i..iii...........i.....i.....ii...i.i.ii..............i...ii..ii.i.. 100/111
[01:01:23] ..iiii.....
[01:01:23] [01:01:23] finished in 3.289
[01:01:23] travis_fold:end:test_codegen
---
[01:19:32] .................................................................................................... 400/961
[01:19:43] .....................................iiii........ii................................................. 500/961
[01:19:48] .................................................................................................... 600/961
[01:19:59] .....................................................................................iiii........... 700/961
[01:20:12] .........................................F.......................................................... 800/961
[01:20:25] ..........iiii...............................................
[01:20:25] failures:
[01:20:25] [01:20:25] ---- process.rs - process::Stdio::from (line 1114) stdout ----
[01:20:25] ---- process.rs - process::Stdio::from (line 1114) stdout ----
[01:20:25] error: expected one of `.`, `;`, `?`, or an operator, found `assert_eq`
[01:20:25] |
[01:20:25] 12 | .output()?
[01:20:25] 12 | .output()?
[01:20:25] | - expected one of `.`, `;`, `?`, or an operator here
[01:20:25] 13 | [01:20:25] 14 | assert_eq!(reverse.stdout, b"!dlrow ,olleH");
[01:20:25] | ^^^^^^^^^ unexpected token
[01:20:25] error: unused import: `std::process::Command`
[01:20:25] --> process.rs:1116:5
[01:20:25] |
[01:20:25] 5 | use std::process::Command;
---
[01:20:25] 1 | #![deny(warnings)]
[01:20:25] | ^^^^^^^^
[01:20:25] = note: #[deny(unused_imports)] implied by #[deny(warnings)]
[01:20:25] [01:20:25] thread 'process.rs - process::Stdio::from (line 1114)' panicked at 'couldn't compile the test', librustdoc/test.rs:332:13
[01:20:25] [01:20:25] [01:20:25] failures:
[01:20:25] process.rs - process::Stdio::from (line 1114)
[01:20:25] process.rs - process::Stdio::from (line 1114)
[01:20:25] [01:20:25] test result: FAILED. 936 passed; 1 failed; 24 ignored; 0 measured; 0 filtered out
[01:20:25] [01:20:25] error: test failed, to rerun pass '--doc'
[01:20:25] [01:20:25] [01:20:25] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:138dc128
travis_time:start:138dc128
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:00c5b9c8
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

kennytm · 2018-10-20T05:28:51Z

@octronics Yes.

kennytm

r=me after this is fixed and all commits squashed into a single commit.

Add a basic summary and an example to From `ChildStdin`, `ChildStdout`, `ChildStderr`, `File` implementations.

octronics · 2018-10-24T20:04:51Z

Squashed and rebase on top of current master.

kennytm · 2018-10-25T02:54:42Z

Thank you!

@bors r+ rollup

bors · 2018-10-25T02:54:43Z

📌 Commit 0b82e03 has been approved by kennytm

Documents `From` implementations for `Stdio` This PR solves part of rust-lang#51430 by adding a basic summary and an example to each `impl From` inside `process` module (`ChildStdin`, `ChildStdout`, `ChildStderr`, `File`). It does not document if the conversions allocate memory and how expensive they are.

@ghost

Rollup of 22 pull requests Successful merges: - #53507 (Add doc for impl From for Waker) - #53931 (Gradually expanding libstd's keyword documentation) - #54965 (update tcp stream documentation) - #54977 (Accept `Option<Box<$t:ty>>` in macro argument) - #55138 (in which unused-parens suggestions heed what the user actually wrote) - #55173 (Suggest appropriate syntax on missing lifetime specifier in return type) - #55200 (Documents `From` implementations for `Stdio`) - #55245 (submodules: update clippy from 5afdf8b to b1d0343) - #55247 (Clarified code example in char primitive doc) - #55251 (Fix a typo in the documentation of RangeInclusive) - #55253 (only issue "variant of the expected type" suggestion for enums) - #55254 (Correct trailing ellipsis in name_from_pat) - #55269 (fix typos in various places) - #55282 (Remove redundant clone) - #55285 (Do some copy editing on the release notes) - #55291 (Update stdsimd submodule) - #55296 (Set RUST_BACKTRACE=0 for rustdoc-ui/failed-doctest-output.rs) - #55306 (Regression test for #54478.) - #55328 (Fix doc for new copysign functions) - #55340 (Operands no longer appear in places) - #55345 (Remove is_null) - #55348 (Update RELEASES.md after destabilization of non_modrs_mods) Failed merges: r? @ghost

rust-highfive assigned kennytm Oct 19, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 19, 2018

kennytm reviewed Oct 24, 2018
View reviewed changes

Comment threadsrc/libstd/process.rs Outdated

Documents From implementations for Stdio
0b82e03
Add a basic summary and an example to From `ChildStdin`, `ChildStdout`, `ChildStderr`, `File` implementations.

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 25, 2018

kennytm mentioned this pull request Oct 25, 2018
Rollup of 28 pull requests #55320
Closed

emilyalbini mentioned this pull request Oct 25, 2018
Rollup of 22 pull requests #55347
Merged

bors merged commit 0b82e03 into rust-lang:masterOct 25, 2018

octronics deleted the gh51430 branch October 25, 2018 17:55

Uh oh!

Uh oh!

Conversation

octronics commented Oct 19, 2018

Uh oh!

rust-highfive commented Oct 19, 2018

Uh oh!

kennytm commented Oct 19, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

octronics commented Oct 19, 2018

Uh oh!

octronics commented Oct 19, 2018

Uh oh!

rust-highfive commented Oct 19, 2018

Uh oh!

kennytm commented Oct 19, 2018

Uh oh!

octronics commented Oct 19, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kennytm commented Oct 19, 2018

Uh oh!

octronics commented Oct 19, 2018

Uh oh!

octronics commented Oct 19, 2018

Uh oh!

kennytm commented Oct 19, 2018

Uh oh!

octronics commented Oct 19, 2018

Uh oh!

rust-highfive commented Oct 19, 2018

Uh oh!

rust-highfive commented Oct 19, 2018

Uh oh!

kennytm commented Oct 20, 2018

Uh oh!

kennytm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

octronics commented Oct 24, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kennytm commented Oct 25, 2018

Uh oh!

bors commented Oct 25, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kennytm commented Oct 19, 2018•
edited
Loading

octronics commented Oct 19, 2018•
edited
Loading

octronics commented Oct 24, 2018•
edited
Loading