//! Construction authority for region-bound graphs with stable node identities.

//!

//! Typed opaque wrappers keep their payloads and links private. They check all

//! linked nodes before writing a payload, then mark the node complete. Payload

//! writes require the builder. Frozen readers require the published graph.

@test mod tests;

use std::lang::alloc;

/// Largest node count represented by a graph.

constant MAX_NODE_COUNT: u32 = 0xffffffff;

/// Exclusive authority to construct one graph.

export opaque record Builder: 'g {

    /// Unique identity shared by this graph's nodes.

    owner: &'g u8,

    /// Number of reserved node identities.

    count: u32,

    /// Number of nodes whose payloads are not complete.

    pending: u32,

}

/// Stable identity retained by a typed node wrapper.

export opaque record Node: 'g + Copy {

    /// Identity of the graph that owns this node.

    owner: &'g u8,

    /// Completion state controlled by the graph builder.

    initialized: &'g cell bool,

}

/// Shared authority to read a completed graph.

export opaque record Frozen: 'g + Copy {

    /// Identity of the graph that owns all published nodes.

    owner: &'g u8,

    /// Number of published node identities.

    count: u32,

}

/// Invalid access through a graph capability.

export union Error: Copy {

    /// The node belongs to a different graph.

    ForeignNode,

}

/// A graph that cannot yet be published.

export union FreezeError: 'g {

    /// Construction authority for the graph that still has pending nodes.

    Incomplete(Builder 'g),

}

/// Create an empty graph whose identity lives in the allocation session.

export fn new 'g (storage: &Session 'g) -> Builder 'g throws (alloc::AllocError) {

    let owner = try storage.new(0 as u8);

    return Builder 'g { owner: &*owner, count: 0, pending: 0 };

}

/// Reserve a stable node identity before its typed payload is complete.

/// Allocation failure leaves the builder unchanged.

export fn reserve 'g (builder: &mut Builder 'g, storage: &Session 'g) -> Node 'g

    throws (alloc::AllocError)

{

    if builder.count == MAX_NODE_COUNT {

        throw alloc::AllocError::OutOfMemory;

    }

    let initialized = try storage.new(false);

    let result = Node 'g { owner: builder.owner, initialized: &cell *initialized };

    set builder.count += 1;

    set builder.pending += 1;

    return result;

}

/// Check a node before reading or writing its typed payload during construction.

/// Typed wrappers must also check every node linked by a payload write.

export fn check 'g (builder: &Builder 'g, node: Node 'g) throws (Error) {

    if builder.owner <> node.owner {

        throw Error::ForeignNode;

    }

}

/// Mark a node complete after its typed payload and links are initialized.

/// Completing an initialized node leaves the pending count unchanged.

export fn complete 'g (builder: &mut Builder 'g, node: Node 'g) throws (Error) {

    try check(builder, node);

    if not *node.initialized {

        assert builder.pending > 0;

        set *node.initialized = true;

        set builder.pending -= 1;

    }

}

/// Return the number of reserved nodes that still need initialization.

export fn pending 'g (builder: &Builder 'g) -> u32 {

    return builder.pending;

}

/// Consume construction authority without publishing the graph.

/// Node identity allocations remain owned by the allocation session.

export fn abandon 'g (builder: Builder 'g) {

    let case Builder 'g { owner: _, count: _, pending: _ } = builder

        else panic "abandon: invalid builder";

}

/// Consume construction authority and publish the completed graph.

/// An incomplete graph returns its builder in the error for recovery.

export fn freeze 'g (builder: Builder 'g) -> Frozen 'g throws (FreezeError 'g) {

    if builder.pending <> 0 {

        throw FreezeError 'g::Incomplete(builder);

    }

    let case Builder 'g { owner, count, pending: _ } = builder

        else panic "freeze: invalid builder";

    return Frozen 'g { owner, count };

}

/// Check a node before reading its typed payload through a frozen graph.

export fn checkFrozen 'g (graph: &Frozen 'g, node: Node 'g) throws (Error) {

    if graph.owner <> node.owner {

        throw Error::ForeignNode;

    }

    assert *node.initialized;

}

/// Return the number of nodes in a frozen graph.

export fn len 'g (graph: &Frozen 'g) -> u32 {

    return graph.count;

}