Span in rustc_span - Rust (original) (raw)
pub struct Span {
lo_or_index: u32,
len_with_tag_or_marker: u16,
ctxt_or_parent_or_marker: u16,
}Expand description
A compressed span.
SpanData is 16 bytes, which is too big to stick everywhere. Span only takes up 8 bytes, with less space for the length, parent and context. The vast majority (99.9%+) of SpanData instances can be made to fit within those 8 bytes. Any SpanData whose fields don’t fit into a Span are stored in a separate interner table, and the Span will index into that table. Interning is rare enough that the cost is low, but common enough that the code is exercised regularly.
An earlier version of this code used only 4 bytes for Span, but that was slower because only 80–90% of spans could be stored inline (even less in very large crates) and so the interner was used a lot more. That version of the code also predated the storage of parents.
There are four different span forms.
Inline-context format (requires non-huge length, non-huge context, and no parent):
span.lo_or_index == span_data.lospan.len_with_tag_or_marker == len == span_data.hi - span_data.lo(must be<= MAX_LEN)span.ctxt_or_parent_or_marker == span_data.ctxt(must be<= MAX_CTXT)
Inline-parent format (requires non-huge length, root context, and non-huge parent):
span.lo_or_index == span_data.lospan.len_with_tag_or_marker & !PARENT_TAG == len == span_data.hi - span_data.lo(must be<= MAX_LEN)span.len_with_tag_or_markerhas top bit (PARENT_TAG) setspan.ctxt_or_parent_or_marker == span_data.parent(must be<= MAX_CTXT)
Partially-interned format (requires non-huge context):
span.lo_or_index == index(indexes into the interner table)span.len_with_tag_or_marker == BASE_LEN_INTERNED_MARKERspan.ctxt_or_parent_or_marker == span_data.ctxt(must be<= MAX_CTXT)
Fully-interned format (all cases not covered above):
span.lo_or_index == index(indexes into the interner table)span.len_with_tag_or_marker == BASE_LEN_INTERNED_MARKERspan.ctxt_or_parent_or_marker == CTXT_INTERNED_MARKER
The partially-interned form requires looking in the interning table for lo and length, but the context is stored inline as well as interned. This is useful because context lookups are often done in isolation, and inline lookups are quicker.
Notes about the choice of field sizes:
lois 32 bits in bothSpanandSpanData, which means thatlovalues never cause interning. The number of bits needed forlodepends on the crate size. 32 bits allows up to 4 GiB of code in a crate. Having no compression on this field means there is no performance cliff if a crate exceeds a particular size.lenis ~15 bits inSpan(a u16, minus 1 bit for PARENT_TAG) and 32 bits inSpanData, which means that largelenvalues will cause interning. The number of bits needed forlendoes not depend on the crate size. The most common numbers of bits forlenare from 0 to 7, with a peak usually at 3 or 4, and then it drops off quickly from 8 onwards. 15 bits is enough for 99.99%+ of cases, but larger values (sometimes 20+ bits) might occur dozens of times in a typical crate.ctxt_or_parent_or_markeris 16 bits inSpanand two 32 bit fields inSpanData, which means intering will happen ifctxtis large, ifparentis large, or if both values are non-zero. The number of bits needed forctxtvalues depend partly on the crate size and partly on the form of the code. No crates inrustc-perfneed more than 15 bits forctxt_or_parent_or_marker, but larger crates might need more than 16 bits. The number of bits needed forparenthasn’t been measured, becauseparentisn’t currently used by default.
In order to reliably use parented spans in incremental compilation, the dependency to the parent definition’s span. This is performed using the callback SPAN_TRACK to access the query engine.
Reuses the span but adds information like the kind of the desugaring and features that are allowed inside this span.
Internal function to translate between an encoded span and the expanded representation. This function must not be used outside the incremental engine.
Returns true if this span comes from any kind of macro, desugaring or inlining.
Returns true if this is a dummy span with any hygienic context.
This function is used as a fast path when decoding the full SpanData is not necessary. It’s a cut-down version of data_untracked.
Returns whether this span originates in a foreign crate’s external macro.
This is used to test whether a lint should not even begin to figure out whether it should be reported on the current node.
Returns true if span originates in a derive-macro’s expansion.
Return whether span is generated by async or await.
Gate suggestions that would not be appropriate in a context the user didn’t write.
Returns a new span representing an empty span at the beginning of this span.
Returns a new span representing an empty span at the end of this span.
Returns true if hi == lo.
Returns self if self is not the dummy span, and other otherwise.
Returns true if self fully encloses other.
Returns true if self touches other.
Returns true if self touches or adjoins other.
Returns true if the spans are equal with regards to the source text.
Use this instead of == when either span could be generated code, and you only care that they point to the same bytes of source text.
Returns Some(span), where the start is trimmed by the end of other.
Returns Some(span), where the end is trimmed by the start of other.
Returns the source span – this is either the supplied span, or the span for the macro callsite that expanded to it.
The Span for the tokens in the previous macro expansion from which self was generated, if any.
Walk down the expansion ancestors to find a span that’s contained within outer.
The span returned by this method may have a different SyntaxContext as outer. If you need to extend the span, use find_ancestor_inside_same_ctxt instead, because joining spans with different syntax contexts can create unexpected results.
Recursively walk down the expansion ancestors to find the oldest ancestor span with the sameSyntaxContext the initial span.
This method is suitable for peeling through local macro expansions to find the “innermost” span that is still local and shares the same SyntaxContext. For example, given
macro_rules! outer {
($x: expr) => {
inner!($x)
}
}
macro_rules! inner {
($x: expr) => {
format!("error: {}", $x)
//~^ ERROR mismatched types
}
}
fn bar(x: &str) -> Result<(), Box<dyn std::error::Error>> {
Err(outer!(x))
}if provided the initial span of outer!(x) inside bar, this method will recurse the parent callsites until we reach format!("error: {}", $x), at which point it is the oldest ancestor span that is both still local and shares the same SyntaxContext as the initial span.
Edition of the crate from which this span came.
Is this edition 2015?
Are we allowed to use features from the Rust 2018 edition?
Are we allowed to use features from the Rust 2021 edition?
Are we allowed to use features from the Rust 2024 edition?
Returns the source callee.
Returns None if the supplied span has no expansion trace, else returns the ExpnData for the macro definition corresponding to the source callsite.
Checks if a span is “internal” to a macro in which #[unstable]items can be used (that is, a macro marked with#[allow_internal_unstable]).
Checks if this span arises from a compiler desugaring of kind kind.
Returns the compiler desugaring that created this span, or Noneif this span is not from a desugaring.
Checks if a span is “internal” to a macro in which unsafecan be used without triggering the unsafe_code lint. (that is, a macro marked with #[allow_internal_unsafe]).
Splits a span into two composite spans around a certain position.
Check if you can select metavar spans for the given spans to get matching contexts.
Prepare two spans to a combine operation like to or between.
This span, but in a larger context, may switch to the metavariable span if suitable.
Returns a Span that would enclose both self and end.
Note that this can also be used to extend the span “backwards”:start.to(end) and end.to(start) return the same Span.
____ ___
self lorem ipsum end
^^^^^^^^^^^^^^^^^^^^Returns a Span between the end of self to the beginning of end.
____ ___
self lorem ipsum end
^^^^^^^^^^^^^Returns a Span from the beginning of self until the beginning of end.
____ ___
self lorem ipsum end
^^^^^^^^^^^^^^^^^Returns the Span within the syntax context of “within”. This is useful when “self” is an expansion from a macro variable, since this can be used for providing extra macro expansion context for certain errors.
macro_rules! m {
($ident:ident) => { ($ident,) }
}
m!(outer_ident);If “self” is the span of the outer_ident, and “within” is the span of the ($ident,)expr, then this will return the span of the $ident macro variable.
Equivalent of Span::def_site from the proc macro API, except that the location is taken from the self span.
Equivalent of Span::call_site from the proc macro API, except that the location is taken from the self span.
Equivalent of Span::mixed_site from the proc macro API, except that the location is taken from the self span.
Produces a span with the same location as self and context produced by a macro with the given ID and transparency, assuming that macro was defined directly and not produced by some other macro (which is the case for built-in and procedural macros).
Hashes a span in a stable way. We can’t directly hash the span’s BytePosfields (that would be similar to hashing pointers, since those are just offsets into the SourceMap). Instead, we hash the (file name, line, column) triple, which stays the same even if the containing SourceFile has moved within the SourceMap.
Also note that we are hashing byte offsets for the column, not unicode codepoint offsets. For the purpose of the hash that’s sufficient. Also, hashing filenames is expensive so we avoid doing it twice when the span starts and ends in the same file, which is almost always the case.
Tests for self and other values to be equal, and is used by ==.
Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
This method returns an ordering between self and other values if one exists. Read more
Tests less than (for self and other) and is used by the < operator. Read more
Tests less than or equal to (for self and other) and is used by the<= operator. Read more
Tests greater than (for self and other) and is used by the >operator. Read more
Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.
Size: 8 bytes