iowo/crates/ir/src/id.rs

//! Instance identification for instructions and their glue.
//!
//! Instructions as defined in [`crate::instruction::Kind`] and descendants are very useful,
//! but they cannot be directly used as vertices in the graph IR,
//! as there may easily be multiple instructions of the same kind in the same program.
//!
//! Instead, this module offers an alternative way to refer to specific instances:
//!
//! - [`Instruction`]s are referred to as their **byte [`Span`]s** in the source code,
//!   so effectively where they are written in the source code.
//!   (Or if coming from [`crate::semi_human::GraphIr`],
//!   it's just a fictional number floating in space.)
//! - [`Socket`]s contain
//!   - what [`Instruction`] they belong to
//!   - which index they occupy on it
//!
//!   The distinction between [`Input`] and [`Output`] is implemented
//!   as them being different types.

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, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub struct Instruction(pub(super) Span);

impl Instruction {
    /// Where this instruction is written down.
    #[must_use]
    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, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub struct Input(pub(super) Socket);

impl Input {
    #[must_use]
    pub fn socket(&self) -> &Socket {
        &self.0
    }
}

/// 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, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub struct Output(pub(super) Socket);

impl Output {
    #[must_use]
    pub fn socket(&self) -> &Socket {
        &self.0
    }
}

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

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