Module rustc_metadata::index_builder[][src]

🔬 This is a nightly-only experimental API. (rustc_private)

this crate is being loaded from the sysroot, an unstable location; did you mean to load this crate from crates.io via Cargo.toml instead?

Builder types for generating the "item data" section of the metadata. This section winds up looking like this:

<common::data> // big list of item-like things...
   <common::data_item> // ...for most def-ids, there is an entry.
   </common::data_item>
</common::data>

As we generate this listing, we collect the offset of each data_item entry and store it in an index. Then, when we load the metadata, we can skip right to the metadata for a particular item.

In addition to the offset, we need to track the data that was used to generate the contents of each data_item. This is so that we can figure out which HIR nodes contributed to that data for incremental compilation purposes.

The IndexBuilder facilitates both of these. It is created with an EncodingContext (ecx), which it encapsulates. It has one main method, record(). You invoke record like so to create a new data_item element in the list:

index.record(some_def_id, callback_fn, data)

What record will do is to (a) record the current offset, (b) emit the common::data_item tag, and then call callback_fn with the given data as well as the EncodingContext. Once callback_fn returns, the common::data_item tag will be closed.

EncodingContext does not offer the record method, so that we can ensure that common::data_item elements are never nested.

In addition, while the callback_fn is executing, we will push a task MetaData(some_def_id), which can then observe the reads/writes that occur in the task. For this reason, the data argument that is given to the callback_fn must implement the trait DepGraphRead, which indicates how to register reads on the data in this new task (note that many types of data, such as DefId, do not currently require any reads to be registered, since they are not derived from a HIR node). This is also why we give a callback fn, rather than taking a closure: it allows us to easily control precisely what data is given to that fn.

Re-exports

use encoder::EncodeContext;
use index::Index;
use schema::*;
use isolated_encoder::IsolatedEncoder;
use rustc::hir;
use rustc::hir::def_id::DefId;
use rustc::ty::TyCtxt;
use syntax::ast;
use std::ops::Deref;
use std::ops::DerefMut;

Structs

FromId [
Experimental
]

Newtype that can be used to package up misc data extracted from a HIR node that doesn't carry its own id. This will allow an arbitrary T to be passed in, but register a read on the given node-id.

IndexBuilder [
Experimental
]

Builder that can encode new items, adding them into the index. Item encoding cannot be nested.

Untracked [
Experimental
]

Leaks access to a value of type T without any tracking. This is suitable for ambiguous types like usize, which could represent tracked data (e.g., if you read it out of a HIR node) or might not (e.g., if it's an index). Adding in an Untracked is an assertion, essentially, that the data does not need to be tracked (or that read edges will be added by some other way).

Traits

DepGraphRead [
Experimental
]

Trait used for data that can be passed from outside a dep-graph task. The data must either be of some safe type, such as a DefId index, or implement the read method so that it can add a read of whatever dep-graph nodes are appropriate.