Improve hir::map::Map::get_parent_node doc

The documentation says
```
    /// Similar to get_parent, returns the parent node id or id if there is no
    /// parent.
    /// This function returns the immediate parent in the AST, whereas get_parent
    /// returns the enclosing item.
```
One would think that one can walk up the tree by repeatedly calling `get_parent_node` until it returns the argument, and then work on the `NodeId`s that arise. However, that is not true: `get_parent_node` will return id 0 (the crate itself) for items that sit directly in the crate; calling `get` on that `NodeId` will panic.

So, the fact that `get_parent_node` returns the root when passed the root is actually not really useful, because the root itself is already a somewhat degenerate node. This improves the doc so hopefully people writing code that "walks up the tree" don't run into this issue like I did...

incr.comp.: Properly incorporate symbol linkage and visibility into CGU hash.

This PR fixes the way the CGU hash for incr. comp. is computed. The CGU hash represents which `TransItems` are emitted into which codegen unit with which linkage and visibility. Before the new, LLVM-independent symbol internalizer the CGU hash did not accurately contain `TransItem` linkage and visibility because we would not enable symbol internalization in incremental mode anyway. The new internalizer is also run in incremental mode which uncovered the inaccuracy of CGU hashing. Luckily, the fix is rather simple.

r? @EddyB
cc @nikomatsakis

rustdoc: shrink headings in non-top-level docblocks

Headings in per-method docs are often bigger than the function names/signatures themselves, so this tones those down to accentuate the methods.

![screenshot of this change on Vec::swap_remove](https://user-images.githubusercontent.com/5217170/28849380-6116a830-76dc-11e7-8ce2-04433d09463a.png)

Fixes #17193

Fix quadratic performance with lots of use statements

This fixes 2 problems that caused quadratic performance when lots of use-statements were present. After this patch, performance is linear (and very fast) even with 1M uses.

Fixes #43572.
Fixes #43573.

r? @EddyB

Rollup of 6 pull requests

- Successful merges: #43389, #43423, #43581, #43585, #43597, #43598
- Failed merges:

Derive `Hash` on `AssociatedKind`.

This is a trivial change useful in downstream code poking in rustc's
innards, in particular the semver verification tool I'm currently working on.

r? @EddyB

Fix the Solaris pthread_t raw type in std to match what's in libc

The old type causes failures when building cargo 0.20.0 after rust-lang/libc@8304e06b5.

Improve docs & doc examples for HashSet.

None

rustc: Inline bitwise modification operators

These need to be inlined across crates to avoid showing up as one-instruction
functions in profiles! In the benchmark from #43578 this decreased the
translation item collection step from 30s to 23s, and looks like it also allowed
vectorization elsewhere of the operations!

Add simple docs example for struct Cell

Thread through the original error when opening archives

This updates the management of opening archives to thread through the original
piece of error information from LLVM over to the end consumer, trans.

Gate LLVMRustHasFeature on LLVM_RUSTLLVM

Commit c4710203 in #43492 make `LLVMRustHasFeature` "more robust"
by using `getFeatureTable()`.  However, this function is specific to
Rust's own LLVM fork, not upstream LLVM-4.0, so we need to use
`#if LLVM_RUSTLLVM` to guard this call.

Closes #43555.

rustc_mir: don't build unused unwind cleanup blocks

When building a scope exit, don't build unwind cleanup blocks unless they will actually be used by the unwind path of a drop - the unused blocks are removed by SimplifyCfg, but they can cause a significant performance slowdown before they are removed. That fixes #43511.

Also a few other small MIR cleanups & optimizations.

r? @EddyB

This is a trivial change useful in downstream code poking in rustc's
innards.

add documentation for function pointers as a primitive

This PR adds a new kind of primitive to the standard library documentation: Function pointers. It's useful to be able to discuss them separately from closure-trait-objects, and to have something to point to when discussing function pointers as a *type* and not a *trait*.

Fixes #17104

The old type causes failures when building cargo 0.20.0 after
changeset 8304e06b5 in the libc repo.

Run translation and LLVM in parallel when compiling with multiple CGUs

This is still a work in progress but the bulk of the implementation is done, so I thought it would be good to get it in front of more eyes.

This PR makes the compiler start running LLVM while translation is still in progress, effectively allowing for more parallelism towards the end of the compilation pipeline. It also allows the main thread to switch between either translation or running LLVM, which allows to reduce peak memory usage since not all LLVM module have to be kept in memory until linking. This is especially good for incr. comp. but it works just as well when running with `-Ccodegen-units=N`.

In order to help tuning and debugging the work scheduler, the PR adds the `-Ztrans-time-graph` flag which spits out html files that show how work packages where scheduled:
![Building regex](https://user-images.githubusercontent.com/1825894/28679272-f6752bd8-72f2-11e7-8a6c-56207855ce95.png)
(red is translation, green is llvm)

One side effect here is that `-Ztime-passes` might show something not quite correct because trans and LLVM are not strictly separated anymore. I plan to have some special handling there that will try to produce useful output.

One open question is how to determine whether the trans-thread should switch to intermediate LLVM processing.

TODO:
- [x] Restore `-Z time-passes` output for LLVM.
- [x] Update documentation, esp. for work package scheduling.
- [x] Tune the scheduling algorithm.

cc @alexcrichton @rust-lang/compiler

trans::mir::constant - fix assignment error recovery

trans::mir::constant - fix assignment error recovery

We used to not store anything when the RHS of an assignment returned an error, which caused ICEs downstream.

Fixes #43197.

Instead of finding the next free disambiguator by incrementing it until
you find a place, store the next available disambiguator in an hash-map.

This avoids O(n^2) performance when lots of items have the same
un-disambiguated `DefPathData` - e.g. all `use` items have
`DefPathData::Misc`.

We already had a cache for file contents, but we read the source-file
before testing the cache, causing obvious slowness, so this just avoids
loading the source-file when the cache already has the contents.

add docs for references as a primitive

Just like #43529 did for function pointers, here is a new primitive page for references.

This PR will pull in impls on references if it's a reference to a generic type parameter. Initially i was only able to pull in impls that were re-exported from another crate; crate-local impls got a different representation in the AST, and i had to change how types were resolved when cleaning it. (This is the change at the bottom of `librustdoc/clean/mod.rs`, in `resolve_type`.) I'm unsure the full ramifications of the change, but from what it looks like, it shouldn't impact anything major. Likewise, references to generic type parameters also get the `&'a [mut]` linked to the new page.

cc @rust-lang/docs: Is this sufficient information? The listing of trait impls kinda feels redundant (especially if we can get the automated impl listing sorted again), but i still think it's useful to point out that you can use these in a generic context.

Fixes #15654

resolve: Try to fix instability in import suggestions

cc https://github.com/rust-lang/rust/pull/42033

`lookup_import_candidates` walks module graph in DFS order and skips modules that were already visited (which is correct because there can be cycles).
However it means that if we visited `std::prelude::v1::Result::Ok` first, we will never visit `std::result::Result::Ok` because `Result` will be skipped as already visited (note: enums are also modules here), and otherwise, if we visited `std::result::Result::Ok` first, we will never get to `std::prelude::v1::Result::Ok`.
What child module of `std` (`prelude` or `result`) we will visit first, depends on randomized hashing, so we have instability in diagnostics.

With this patch modules' children are visited in stable order in `lookup_import_candidates`, this should fix the issue, but let's see what Travis will say.

r? @oli-obk

Three small fixes for save-analysis

First commit does some naive deduplication of macro uses. We end up with lots of duplication here because of the weird way we get this data (we extract a use for every span generated by a macro use).

Second commit is basically a typo fix.

Third commit is a bit interesting, it partially reverts a change from #40939 where temporary variables in format! (and thus println!) got a span with the primary pointing at the value stored into the temporary (e.g., `x` in `println!("...", x)`). If `format!` had a definition it should point at the temporary in the macro def, but since it is built-in, that is not possible (for now), so `DUMMY_SP` is the best we can do (using the span in the callee really breaks save-analysis because it thinks `x` is a definition as well as a reference).

There aren't a test for this stuff because: the deduplication is filtered by any of the users of save-analysis, so it is purely an efficiency change. I couldn't actually find an example for the second commit that we have any machinery to test, and the third commit is tested by the RLS, so there will be a test once I update the RLS version and and uncomment the previously failing tests).

r? @jseyfried

These need to be inlined across crates to avoid showing up as one-instruction
functions in profiles! In the benchmark from #43578 this decreased the
translation item collection step from 30s to 23s, and looks like it also allowed
vectorization elsewhere of the operations!

Commit c4710203 in #43492 make `LLVMRustHasFeature` "more robust"
by using `getFeatureTable()`.  However, this function is specific to
Rust's own LLVM fork, not upstream LLVM-4.0, so we need to use
`#if LLVM_RUSTLLVM` to guard this call.