OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

apply various nits

Browse Source
This commit is contained in:
Niko Matsakis 2017-09-15 16:19:44 -04:00
parent 44e45d9fea
commit 73a4e8db75
5 changed files with 46 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
src/librustc/README.md
View File

@ -57,11 +57,12 @@ rustc_trans rustc_borrowck ... rustc_metadata
syntax_pos syntax_ext
```
The idea is that `rustc_driver`, at the top of this lattice, basically
defines the overall control-flow of the compiler. It doesn't have much
"real code", but instead ties together all of the code defined in the
other crates and defines the overall flow of execution.
The `rustc_driver` crate, at the top of this lattice, is effectively
the "main" function for the rust compiler. It doesn't have much "real
code", but instead ties together all of the code defined in the other
crates and defines the overall flow of execution. (As we transition
more and more to the [query model](ty/maps/README.md), however, the
"flow" of compilation is becoming less centrally defined.)
At the other extreme, the `rustc` crate defines the common and
pervasive data structures that all the rest of the compiler uses

12
src/librustc/hir/README.md
View File

@ -45,10 +45,10 @@ The other reason to setup the representation this way is for better
integration with incremental compilation. This way, if you gain access
to a `&hir::Item` (e.g. for the mod `foo`), you do not immediately
gain access to the contents of the function `bar()`. Instead, you only
gain access to the **id** for `bar()`, and you must some function to
lookup the contents of `bar()` given its id; this gives us a change to
observe that you accessed the data for `bar()` and record the
dependency.
gain access to the **id** for `bar()`, and you must invoke some
function to lookup the contents of `bar()` given its id; this gives us
a chance to observe that you accessed the data for `bar()` and record
the dependency.
### Identifiers in the HIR
@ -117,7 +117,3 @@ associated with an **owner**, which is typically some kind of item
(e.g., `|x, y| x + y`). You can use the HIR map to find find the body
associated with a given def-id (`maybe_body_owned_by()`) or to find
the owner of a body (`body_owner_def_id()`).

5
src/librustc/hir/mod.rs
View File

@ -416,6 +416,7 @@ pub type CrateConfig = HirVec<P<MetaItem>>;
/// The top-level data structure that stores the entire contents of
/// the crate currently being compiled.
///
/// For more details, see [the module-level README](README.md).
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)]
pub struct Crate {
pub module: Mod,
@ -935,9 +936,9 @@ pub struct BodyId {
/// (which is an expression), but also the argument patterns, since
/// those are something that the caller doesn't really care about.
///
/// Example:
/// # Examples
///
/// ```rust
/// ```
/// fn foo((x, y): (u32, u32)) -> u32 {
/// x + y
/// }

52
src/librustc/ty/README.md
View File

@ -21,7 +21,7 @@ tcx: TyCtxt<'a, 'gcx, 'tcx>
As you can see, the `TyCtxt` type takes three lifetime parameters.
These lifetimes are perhaps the most complex thing to understand about
the tcx. During rust compilation, we allocate most of our memory in
the tcx. During Rust compilation, we allocate most of our memory in
**arenas**, which are basically pools of memory that get freed all at
once. When you see a reference with a lifetime like `'tcx` or `'gcx`,
you know that it refers to arena-allocated data (or data that lives as
@ -70,18 +70,24 @@ fn maybe_in_inference<'a, 'gcx, 'tcx>(tcx: TyCtxt<'a, 'gcx, 'tcx>, def_id: DefId
### Allocating and working with types
Rust types are represented using the `ty::Ty<'tcx>` type. This is in fact a simple type alias
for a reference with `'tcx` lifetime:
Rust types are represented using the `Ty<'tcx>` defined in the `ty`
module (not to be confused with the `Ty` struct from [the HIR]). This
is in fact a simple type alias for a reference with `'tcx` lifetime:
```rust
pub type Ty<'tcx> = &'tcx TyS<'tcx>;
```
The `TyS` struct defines the actual details of how a type is
represented. The most interesting part of it is the `sty` field, which
contains an enum that lets us test what sort of type this is. For
example, it is very common to see code that tests what sort of type you have
that looks roughly like so:
[the HIR]: ../hir/README.md
You can basically ignore the `TyS` struct -- you will basically never
access it explicitly. We always pass it by reference using the
`Ty<'tcx>` alias -- the only exception I think is to define inherent
methods on types. Instances of `TyS` are only ever allocated in one of
the rustc arenas (never e.g. on the stack).
One common operation on types is to **match** and see what kinds of
types they are. This is done by doing `match ty.sty`, sort of like this:
```rust
fn test_type<'tcx>(ty: Ty<'tcx>) {
@ -92,10 +98,14 @@ fn test_type<'tcx>(ty: Ty<'tcx>) {
}
```
(Note though that doing such low-level tests on types during inference
can be risky, as there are may be inference variables and other things
to consider, or sometimes types are not yet known that will become
known later.).
The `sty` field (the origin of this name is unclear to me; perhaps
structural type?) is of type `TypeVariants<'tcx>`, which is an enum
definined all of the different kinds of types in the compiler.
> NB: inspecting the `sty` field on types during type inference can be
> risky, as there are may be inference variables and other things to
> consider, or sometimes types are not yet known that will become
> known later.).
To allocate a new type, you can use the various `mk_` methods defined
on the `tcx`. These have names that correpond mostly to the various kinds
@ -114,13 +124,13 @@ any inference variables or other "temporary" types, they will be
allocated in the global arena). However, the lifetime `'tcx` is always
a safe approximation, so that is what you get back.
NB. Because types are interned, it is possible to compare them for
equality efficiently using `==` -- however, this is almost never what
you want to do unless you happen to be hashing and looking for
duplicates. This is because often in Rust there are multiple ways to
represent the same type, particularly once inference is involved. If
you are going to be testing for type equality, you probably need to
start looking into the inference code to do it right.
> NB. Because types are interned, it is possible to compare them for
> equality efficiently using `==` -- however, this is almost never what
> you want to do unless you happen to be hashing and looking for
> duplicates. This is because often in Rust there are multiple ways to
> represent the same type, particularly once inference is involved. If
> you are going to be testing for type equality, you probably need to
> start looking into the inference code to do it right.
You can also find various common types in the tcx itself by accessing
`tcx.types.bool`, `tcx.types.char`, etc (see `CommonTypes` for more).
@ -153,7 +163,3 @@ In particular, since they are so common, the `Ty` and `TyCtxt` types
are imported directly. Other types are often referenced with an
explicit `ty::` prefix (e.g., `ty::TraitRef<'tcx>`). But some modules
choose to import a larger or smaller set of names explicitly.

9
src/librustc/ty/context.rs
View File

@ -793,11 +793,10 @@ impl<'tcx> CommonTypes<'tcx> {
}
}
/// The central data structure of the compiler. Keeps track of all the
/// information that typechecker generates so that so that it can be
/// reused and doesn't have to be redone later on.
///
/// See [the README](README.md) for more deatils.
/// The central data structure of the compiler. It stores references
/// to the various **arenas** and also houses the results of the
/// various **compiler queries** that have been performed. See [the
/// README](README.md) for more deatils.
#[derive(Copy, Clone)]
pub struct TyCtxt<'a, 'gcx: 'a+'tcx, 'tcx: 'a> {
gcx: &'a GlobalCtxt<'gcx>,