improve Pin documentation #58574

RalfJung · 2019-02-19T12:24:29Z

Incorporates a bunch of the documentation-related comments that came up when discussing Pin stabilization.

Cc @alexcrichton @withoutboats @cramertj @jonhoo

Fixes #58130

rust-highfive · 2019-02-19T12:24:40Z

r? @Mark-Simulacrum

(rust_highfive has picked a reviewer for you, use r? to override)

src/libcore/pin.rs

Mark-Simulacrum

This looks amazing! Thank you.

I think we may want to consider a beta backport as well if we can land this somewhat quickly so we ship these docs with the stabilization of Pin.

src/libcore/pin.rs

src/libcore/marker.rs

src/libcore/pin.rs

src/libcore/marker.rs

src/libcore/pin.rs

jonhoo · 2019-02-21T13:09:17Z

@RalfJung yup, looks better 👍

Co-Authored-By: RalfJung <[email protected]>

rust-highfive · 2019-02-21T14:49:27Z

The job x86_64-gnu-llvm-6.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.

travis_time:end:0e1299a4:start=1550759715006557272,finish=1550759797359943775,duration=82353386503
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---

[00:03:16] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:16] tidy error: /checkout/src/libcore/pin.rs:18: line longer than 100 chars
[00:03:18] some tidy checks failed
[00:03:18] 
[00:03:18] 
[00:03:18] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:18] 
[00:03:18] 
[00:03:18] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:18] Build completed unsuccessfully in 0:00:45
[00:03:18] Build completed unsuccessfully in 0:00:45
[00:03:18] make: *** [tidy] Error 1
[00:03:18] Makefile:68: recipe for target 'tidy' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:3ab9fa20
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Feb 21 14:40:05 UTC 2019
---
travis_time:end:159ae298:start=1550760006309266550,finish=1550760006313638772,duration=4372222
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:1028cd60
$ 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:05e0012e
travis_time:start:05e0012e
$ 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:085606f0
$ 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)

rust-highfive · 2019-02-21T16:07:09Z

The job x86_64-gnu-llvm-6.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.

travis_time:end:16ad4d2b:start=1550761639141063332,finish=1550761714006509873,duration=74865446541
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[00:57:36]     Checking compiler_builtins v0.1.5
[00:57:37]  Documenting alloc v0.0.0 (/checkout/src/liballoc)
[00:57:42]     Finished release [optimized] target(s) in 37.24s
[00:57:43]  Documenting core v0.0.0 (/checkout/src/libcore)
[00:58:00] warning: `[Pin]` cannot be resolved, ignoring it...
[00:58:00]    --> src/libcore/marker.rs:605:61
[00:58:00]     |
[00:58:00] 605 | /// by controlling the behavior of pointers wrapped in the [`Pin`] wrapper,
[00:58:00]     |
[00:58:00] note: lint level defined here
[00:58:00]    --> src/libcore/lib.rs:63:9
[00:58:00]     |
---
[00:58:12]     Checking rustc_msan v0.0.0 (/checkout/src/librustc_msan)
[00:58:12]     Checking rustc_asan v0.0.0 (/checkout/src/librustc_asan)
[00:58:12]     Checking rustc_lsan v0.0.0 (/checkout/src/librustc_lsan)
[00:58:12]  Documenting std v0.0.0 (/checkout/src/libstd)
[00:58:19] error: `[Pin]` cannot be resolved, ignoring it...
[00:58:19]    --> /checkout/src/libcore/marker.rs:605:61
[00:58:19]     |
[00:58:19] 605 | /// by controlling the behavior of pointers wrapped in the [`Pin`] wrapper,
[00:58:19]     |
[00:58:19] note: lint level defined here
[00:58:19]    --> src/libstd/lib.rs:209:9
[00:58:19]     |
[00:58:19]     |
[00:58:19] 209 | #![deny(intra_doc_link_resolution_failure)]
[00:58:19]     |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[00:58:19]     = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
[00:58:19] 
[00:58:19] error: Could not document `std`.
[00:58:19] 
[00:58:19] Caused by:
[00:58:19]   process didn't exit successfully: `/checkout/obj/build/bootstrap/debug/rustdoc --crate-name std src/libstd/lib.rs --color always --target x86_64-unknown-linux-gnu -o /checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/doc --cfg 'feature="backtrace"' --cfg 'feature="backtrace-sys"' --cfg 'feature="compiler_builtins"' --cfg 'feature="compiler_builtins_c"' --cfg 'feature="default"' --cfg 'feature="panic-unwind"' --cfg 'feature="panic_unwind"' --cfg 'feature="std_detect_dlsym_getauxval"' --cfg 'feature="std_detect_file_io"' --markdown-css rust.css --markdown-no-toc --generate-redirect-pages --index-page /checkout/src/doc/index.md -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/release/deps --extern alloc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/liballoc-9e6c0311b71511c6.rmeta --extern backtrace_sys=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libbacktrace_sys-f13b165ed9b4dd57.rmeta --extern compiler_builtins=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libcompiler_builtins-d54fe968dea87029.rmeta --extern core=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libcore-84e5b9599b1b7754.rmeta --extern libc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/liblibc-a69fda92b07aedd5.rmeta --extern panic_abort=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libpanic_abort-349a3e5cce9f18ee.rmeta --extern panic_unwind=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libpanic_unwind-d7c48504ff1056b6.rmeta --extern rustc_demangle=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_demangle-20814bca47e9a554.rmeta --extern rustc_asan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_asan-8bc4c4bf1d4ec8f0.rmeta --extern rustc_lsan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_lsan-0814373332ff833c.rmeta --extern rustc_msan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_msan-655667bc8a1522d0.rmeta --extern rustc_tsan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_tsan-5756fbda854daecf.rmeta --extern unwind=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libunwind-5e31c590860d0940.rmeta` (exit code: 1)
[00:58:19] 
[00:58:19] 
[00:58:19] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "rustdoc" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-Z" "unstable-options" "-p" "std" "--" "--markdown-css" "rust.css" "--markdown-no-toc" "--generate-redirect-pages" "--index-page" "/checkout/src/doc/index.md"
[00:58:19] 
[00:58:19] 
[00:58:19] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap doc
[00:58:19] Build completed unsuccessfully in 0:06:18
[00:58:19] Build completed unsuccessfully in 0:06:18
[00:58:19] Makefile:18: recipe for target 'all' failed
[00:58:19] make: *** [all] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:16cd8ef9
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Feb 21 16:07:03 UTC 2019
---
travis_time:end:1ad7246a:start=1550765224356712004,finish=1550765224363435729,duration=6723725
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:16d6af00
$ 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:0d9bc12f
travis_time:start:0d9bc12f
$ 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:0f086856
$ 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)

RalfJung · 2019-02-21T22:15:30Z

All right, I think I resolved all comments. Let's land this! p=1 because we want to backport it.

@bors r=Mark-Simulacrum p=1

bors · 2019-02-21T22:15:31Z

📌 Commit 497439c has been approved by Mark-Simulacrum

bors · 2019-02-21T22:15:32Z

🌲 The tree is currently closed for pull requests below priority 99, this pull request will be tested once the tree is reopened

Centril · 2019-02-21T22:16:38Z

@bors p=30

bors · 2019-02-22T04:11:30Z

⌛ Testing commit 497439c with merge c6fd027...

@alexcrichton

improve Pin documentation Incorporates a bunch of the documentation-related comments that came up when discussing `Pin` stabilization. Cc @alexcrichton @withoutboats @cramertj @jonhoo Fixes #58130

bors · 2019-02-22T06:52:34Z

☀️ Test successful - checks-travis, status-appveyor
Approved by: Mark-Simulacrum
Pushing c6fd027 to master...

bors · 2019-02-22T06:52:44Z

☀️ Test successful - checks-travis, status-appveyor
Approved by: Mark-Simulacrum
Pushing c6fd027 to master...

RalfJung · 2019-02-22T08:21:29Z

@Mark-Simulacrum Do I have to do anything for the beta backport, or are you taking care of that?

Mark-Simulacrum · 2019-02-22T13:03:43Z

The release team will take care of it.

@pietroalbini

Beta rollups - #58649 - #58592 - #58574 - #58227 - #58056 - #57859 - #57710 A few of these are via #58641. r? @pietroalbini

improve Pin documentation

4059889

rust-highfive assigned Mark-Simulacrum Feb 19, 2019

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

Nemo157 reviewed Feb 19, 2019

View reviewed changes

src/libcore/pin.rs Outdated Show resolved Hide resolved

RalfJung mentioned this pull request Feb 19, 2019

Expand Pinning documentation #58130

Closed

Mark-Simulacrum reviewed Feb 19, 2019

View reviewed changes