iowo/crates/ir/src/lib.rs

use std::ops::RangeInclusive;

use serde::{Deserialize, Serialize};

pub mod instruction;

pub type Map<K, V> = ahash::AHashMap<K, V>;
pub type Set<V> = ahash::AHashSet<V>;

/// # Errors
///
/// Returns an error if the parsed source is not a valid graph IR.
pub fn from_ron(source: &str) -> ron::error::SpannedResult<GraphIr> {
    ron::from_str(source)
}

/// The toplevel representation of a whole pipeline.
///
/// Pipelines may not be fully linear. They may branch out and recombine later on.
/// As such, the representation for them which is currently used is a
/// [**D**irected **A**cyclic **G**raph](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
/// .
///
/// For those who are already familiar with graphs, a DAG is one, except that:
///
/// - It is **directed**: Edges have a direction they point to.
///   In this case, edges point from the outputs of streamers to inputs of consumers.
/// - It is **acyclic**: Those directed edges may not form loops.
///   In other words, if one follows edges only in their direction, it must be impossible
///   to come back to an already visited node.
///
/// Here, if an edge points from _A_ to _B_ (`A --> B`),
/// then _A_ is called a **dependency** of _B_,
/// and _B_ is called a **dependent** of _A_.
///
/// The DAG also enables another neat operation:
/// [Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting).
/// This allows to put the entire graph into a linear list,
/// where it's guaranteed that once a vertex is visited,
/// all dependencies of it will have been visited already as well.
///
/// The representation used here in specific is a bit more complicated,
/// since **instructions** directly aren't just connected to one another,
/// but their **sockets** are instead.
///
/// So the vertices of the DAG are the **sockets**
/// (which are either [`id::Input`] or [`id::Output`] depending on the direction),
/// and each **socket** in turn belongs to an **instruction**.
#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
pub struct GraphIr {
    /// "Backbone" storage of all **instruction** IDs to
    /// what **kind of instruction** they are.
    instructions: Map<id::Instruction, instruction::Kind>,

    /// How the data flows forward. **Dependencies** map to **dependents** here.
    edges: Map<id::Output, Set<id::Input>>,
    /// How the data flows backward. **Dependents** map to **dependencies** here.
    rev_edges: Map<id::Input, Set<id::Output>>,
}

pub mod id {
    use serde::{Deserialize, Serialize};

    use crate::Span;

    /// One specific instruction, and where it is found in code.
    ///
    /// It does **not** contain what kind of instruction this is.
    /// Refer to [`crate::instruction::Kind`] for this instead.
    #[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
    pub struct Instruction(Span);

    impl Instruction {
        /// Where this instruction is written down.
        pub fn span(&self) -> &Span {
            &self.0
        }
    }

    /// On an **instruction**, accepts incoming data.
    ///
    /// An **instruction** cannot run if any of these are not connected.
    #[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
    pub struct Input(Socket);

    /// On an **instruction**, returns outgoing data to be fed to [`Input`]s.
    ///
    /// In contrast to [`Input`]s, [`Output`]s may be used or unused.
    #[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
    pub struct Output(Socket);

    /// An unspecified socket on a specific **instruction**,
    /// and where it is on that **instruction**.
    #[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
    pub struct Socket {
        pub belongs_to: Instruction,
        pub index: SocketIdx,
    }

    /// Where a [`Socket`] is on an **instruction**.
    #[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
    pub struct SocketIdx(pub u16);
}

#[derive(Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
pub struct Span {
    range: RangeInclusive<usize>,
}