Skip to main content

GraphBuilder

Struct GraphBuilder 

Source
pub struct GraphBuilder { /* private fields */ }
Expand description

Accumulates units and edges, then validates them into a BuildGraph.

Identifiers are handed out in insertion order, so an adapter that wants a canonical unit order inserts in that order. The graph never reorders units, so identifiers stay meaningful to the code that built it.

Implementations§

Source§

impl GraphBuilder

Source

pub fn new() -> Self

An empty builder.

Source

pub fn with_capacity(units: usize) -> Self

An empty builder with room for units units already reserved.

Examples found in repository?
examples/scaling.rs (line 33)
31fn build(units: usize, fan_in: usize) -> Result<BuildGraph, Box<dyn Error>> {
32    let tenths = NonZeroU64::new(10).ok_or("ten is not zero")?;
33    let mut builder = GraphBuilder::with_capacity(units);
34    let mut ids = Vec::with_capacity(units);
35    for i in 0..units {
36        let total = weight(i);
37        let unit = Unit {
38            package: format!("p{i}"),
39            version: "1.0.0".to_owned(),
40            target: format!("t{i}"),
41            kind: if is_opaque(i) {
42                UnitKind::ProcMacro
43            } else {
44                UnitKind::Lib
45            },
46            total: Millis::new(total),
47            // A library emits metadata about seven tenths of the way through, which is what the
48            // dev-profile builds measured in docs/validation.md do.
49            metadata_at: if is_opaque(i) {
50                None
51            } else {
52                Some(Millis::new(total).scaled(7, tenths))
53            },
54            requires_full_closure: is_opaque(i),
55        };
56        ids.push(builder.add_unit(unit)?);
57    }
58    for i in 0..units {
59        for k in 1..=fan_in {
60            let Some(back) = i.checked_sub(k * 3) else {
61                continue;
62            };
63            let (Some(&from), Some(&to)) = (ids.get(back), ids.get(i)) else {
64                continue;
65            };
66            // A metadata edge requires the producer to emit metadata and the consumer not to link.
67            let kind = if !is_opaque(back) && !is_opaque(i) {
68                EdgeKind::Metadata
69            } else {
70                EdgeKind::Full
71            };
72            builder.add_edge(from, to, kind)?;
73        }
74    }
75    Ok(builder.build()?)
76}
Source

pub fn add_unit(&mut self, unit: Unit) -> Result<UnitId, GraphError>

Adds a unit and returns its identifier.

§Errors

GraphError::UnitLimitExceeded if the graph would exceed MAX_UNITS.

Examples found in repository?
examples/scaling.rs (line 56)
31fn build(units: usize, fan_in: usize) -> Result<BuildGraph, Box<dyn Error>> {
32    let tenths = NonZeroU64::new(10).ok_or("ten is not zero")?;
33    let mut builder = GraphBuilder::with_capacity(units);
34    let mut ids = Vec::with_capacity(units);
35    for i in 0..units {
36        let total = weight(i);
37        let unit = Unit {
38            package: format!("p{i}"),
39            version: "1.0.0".to_owned(),
40            target: format!("t{i}"),
41            kind: if is_opaque(i) {
42                UnitKind::ProcMacro
43            } else {
44                UnitKind::Lib
45            },
46            total: Millis::new(total),
47            // A library emits metadata about seven tenths of the way through, which is what the
48            // dev-profile builds measured in docs/validation.md do.
49            metadata_at: if is_opaque(i) {
50                None
51            } else {
52                Some(Millis::new(total).scaled(7, tenths))
53            },
54            requires_full_closure: is_opaque(i),
55        };
56        ids.push(builder.add_unit(unit)?);
57    }
58    for i in 0..units {
59        for k in 1..=fan_in {
60            let Some(back) = i.checked_sub(k * 3) else {
61                continue;
62            };
63            let (Some(&from), Some(&to)) = (ids.get(back), ids.get(i)) else {
64                continue;
65            };
66            // A metadata edge requires the producer to emit metadata and the consumer not to link.
67            let kind = if !is_opaque(back) && !is_opaque(i) {
68                EdgeKind::Metadata
69            } else {
70                EdgeKind::Full
71            };
72            builder.add_edge(from, to, kind)?;
73        }
74    }
75    Ok(builder.build()?)
76}
Source

pub fn add_edge( &mut self, from: UnitId, to: UnitId, kind: EdgeKind, ) -> Result<(), GraphError>

Records that to depends on from.

Adding the same pair twice keeps whichever kind releases the consumer later, because keeping the weaker of two stated constraints would make the analysis optimistic.

§Errors

GraphError::UnknownUnit if either index is outside this builder, which is a bounds check and not a check of where the identifier came from, and GraphError::SelfDependency if they are the same unit.

Examples found in repository?
examples/scaling.rs (line 72)
31fn build(units: usize, fan_in: usize) -> Result<BuildGraph, Box<dyn Error>> {
32    let tenths = NonZeroU64::new(10).ok_or("ten is not zero")?;
33    let mut builder = GraphBuilder::with_capacity(units);
34    let mut ids = Vec::with_capacity(units);
35    for i in 0..units {
36        let total = weight(i);
37        let unit = Unit {
38            package: format!("p{i}"),
39            version: "1.0.0".to_owned(),
40            target: format!("t{i}"),
41            kind: if is_opaque(i) {
42                UnitKind::ProcMacro
43            } else {
44                UnitKind::Lib
45            },
46            total: Millis::new(total),
47            // A library emits metadata about seven tenths of the way through, which is what the
48            // dev-profile builds measured in docs/validation.md do.
49            metadata_at: if is_opaque(i) {
50                None
51            } else {
52                Some(Millis::new(total).scaled(7, tenths))
53            },
54            requires_full_closure: is_opaque(i),
55        };
56        ids.push(builder.add_unit(unit)?);
57    }
58    for i in 0..units {
59        for k in 1..=fan_in {
60            let Some(back) = i.checked_sub(k * 3) else {
61                continue;
62            };
63            let (Some(&from), Some(&to)) = (ids.get(back), ids.get(i)) else {
64                continue;
65            };
66            // A metadata edge requires the producer to emit metadata and the consumer not to link.
67            let kind = if !is_opaque(back) && !is_opaque(i) {
68                EdgeKind::Metadata
69            } else {
70                EdgeKind::Full
71            };
72            builder.add_edge(from, to, kind)?;
73        }
74    }
75    Ok(builder.build()?)
76}
Source

pub fn build(self) -> Result<BuildGraph, GraphError>

Validates the accumulated units and edges.

§Errors

GraphError::MetadataAfterCompletion if a unit emits metadata after it finishes, GraphError::MetadataEdgeFromOpaqueUnit if a metadata edge leaves a unit that emits no metadata, and GraphError::Cycle if the dependencies are not acyclic.

Examples found in repository?
examples/scaling.rs (line 75)
31fn build(units: usize, fan_in: usize) -> Result<BuildGraph, Box<dyn Error>> {
32    let tenths = NonZeroU64::new(10).ok_or("ten is not zero")?;
33    let mut builder = GraphBuilder::with_capacity(units);
34    let mut ids = Vec::with_capacity(units);
35    for i in 0..units {
36        let total = weight(i);
37        let unit = Unit {
38            package: format!("p{i}"),
39            version: "1.0.0".to_owned(),
40            target: format!("t{i}"),
41            kind: if is_opaque(i) {
42                UnitKind::ProcMacro
43            } else {
44                UnitKind::Lib
45            },
46            total: Millis::new(total),
47            // A library emits metadata about seven tenths of the way through, which is what the
48            // dev-profile builds measured in docs/validation.md do.
49            metadata_at: if is_opaque(i) {
50                None
51            } else {
52                Some(Millis::new(total).scaled(7, tenths))
53            },
54            requires_full_closure: is_opaque(i),
55        };
56        ids.push(builder.add_unit(unit)?);
57    }
58    for i in 0..units {
59        for k in 1..=fan_in {
60            let Some(back) = i.checked_sub(k * 3) else {
61                continue;
62            };
63            let (Some(&from), Some(&to)) = (ids.get(back), ids.get(i)) else {
64                continue;
65            };
66            // A metadata edge requires the producer to emit metadata and the consumer not to link.
67            let kind = if !is_opaque(back) && !is_opaque(i) {
68                EdgeKind::Metadata
69            } else {
70                EdgeKind::Full
71            };
72            builder.add_edge(from, to, kind)?;
73        }
74    }
75    Ok(builder.build()?)
76}

Trait Implementations§

Source§

impl Clone for GraphBuilder

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for GraphBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for GraphBuilder

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.