3. Running `cbindgen > reowolf.h` from the root will overwrite the header file. This is only necessary to update it.  

## Short User Overview

The bulk of the library's functionality is exposed to the user in two types: 

1. `protocol::ProtocolDescription` 

1. `runtime::Connector` 

The former is created using `parse`. For the most part, the user is not expected to interact much with the structure, only passing it to the connector as a communication session is being set up.

The latter is created with `new`, configured with methods such as `new_net_port` and `add_component`, and connected via `connect`, whereafter it can be used for multi-party communication through methods `put`, `get`, `next_batch`, and `sync`.

## Contributor Overview

The details of the implementation are best understood by reading the doc comments, starting from the procedures listed in the section above. It is suggested to first/also refer to the Reowolf project's companion documentation (link TODO) for a higher level overview of the goals and design of the implementation.

/// Used by various distributed algorithms to identify connectors.

/// Used in conjunction with the `ConnectorId` type to create identifiers for ports and components

/// Generalization of a port/component identifier

/// Identifier of a component in a session

#[derive(

    Copy, Clone, Eq, PartialEq, Ord, Hash, PartialOrd, serde::Serialize, serde::Deserialize,

)]

pub struct ComponentId(Id); // PUB because it can be returned by errors

/// Identifier of a port in a session

/// A safely aliasable heap-allocated payload of message bytes

/// "Orientation" of a port, determining whether they can send or receive messages with `put` and `get` respectively.

/// "Orientation" of a transport-layer network endpoint, dictating how it's connection procedure should

/// be conducted. Corresponds with connect() / accept() familiar to TCP socket programming.

    /// Create a new payload of uninitialized bytes with the given length.

    /// Returns the length of the payload's byte sequence

    /// Allows shared reading of the payload's contents

    /// Allows mutation of the payload's contents.

    /// Results in a deep copy in the event this payload is aliased.

    pub fn as_mut_vec(&mut self) -> &mut Vec<u8> {

        Arc::make_mut(&mut self.0)

    /// Modifies this payload, concatenating the given immutable payload's contents.

    /// Results in a deep copy in the event this payload is aliased.

        let me = self.as_mut_vec();

                if let Some(slot) = payload.as_mut_vec().get_mut(the_index) {

                if let Some(slot) = payload.as_mut_vec().get_mut(the_index) {

    /// Read the message received by the given port in the previous synchronous round.

    pub fn gotten(&self, port: PortId) -> Result<&Payload, GottenError> {

        if let ConnectorPhased::Communication(comm) = &self.phased {

            match &comm.round_result {

                Err(_) => Err(Ge::PreviousSyncFailed),

                Ok(None) => Err(Ge::NoPreviousRound),

                Ok(Some(round_ok)) => round_ok.gotten.get(&port).ok_or(Ge::PortDidntGet),

            }

        } else {

            return Err(Ge::NoPreviousRound);

    /// Creates a new, empty synchronous batch for the connector and selects it.

    /// Subsequent calls to `put` and `get` with populate the new batch with port operations.

        if let ConnectorPhased::Communication(comm) = &mut self.phased {

            comm.native_batches.push(Default::default());

            Ok(comm.native_batches.len() - 1)

        } else {

            Err(WrongStateError)

        }

    /// Add a `put` operation to the connector's currently-selected synchronous batch.

    /// Returns an error if the given port is not owned by the native component,

    /// has the wrong polarity, or is already included in the batch.

    /// Add a `get` operation to the connector's currently-selected synchronous batch.

    /// Returns an error if the given port is not owned by the native component,

    /// has the wrong polarity, or is already included in the batch.

    /// Participate in the completion of the next synchronous round, in which

    /// the native component will perform the set of prepared operations of exactly one

    /// of the synchronous batches. At the end of the procedure, the synchronous

    /// batches will be reset to a singleton set, whose only element is selected, and empty.

    /// The caller yields control over to the connector runtime to faciltiate the underlying

    /// coordination work until either (a) the round is completed with all components' states

    /// updated accordingly, (b) a distributed failure event resets all components'

    /// states to what they were prior to the sync call, or (c) the sync procedure encounters

    /// an unrecoverable error which ends the call early, and breaks the session and connector's

    /// states irreversably.

    /// Note that the (b) case necessitates the success of a distributed rollback procedure,

    /// which this component may initiate, but cannot guarantee will succeed in time or at all.

    /// consequently, the given timeout duration represents a duration in which the connector

    /// will make a best effort to fail the round and return control flow to the caller.

    pub(crate) fn new_component(&mut self, moved_ports: HashSet<PortId>, state: ComponentState) {

    pub(crate) fn new_port_pair(&mut self) -> [PortId; 2] {

    DuplicatePort(PortId),

/// Each Connector structure is the interface between the user's application and a communication session,

/// in which the application plays the part of a (native) component. This structure provides the application

/// with functionality available to all components: the ability to add new channels (port pairs), and to

/// instantiate new components whose definitions are defined in the connector's configured protocol

/// description. Native components have the additional ability to add `dangling' ports backed by local/remote

/// IP addresses, to be coupled with a counterpart once the connector's setup is completed by `connect`.

/// This allows sets of applications to cooperate in constructing shared sessions that span the network.

/// Characterizes a type which can write lines of logging text.

/// The implementations provided in the `logging` module are likely to be sufficient,

/// but for added flexibility, users are able to implement their own loggers for use

/// by connectors.

/// A logger that appends the logged strings to a growing byte buffer

/// A trivial logger that always returns None, such that no logging information is ever written.

/// A logger that writes the logged lines to a given file.

fn duplicate_port(slice: &[PortId]) -> Option<PortId> {

    let mut vec = Vec::with_capacity(slice.len());

    for port in slice.iter() {

        match vec.binary_search(port) {

            Err(index) => vec.insert(index, *port),

            Ok(_) => return Some(*port),

        }

    }

    None

}

    /// Generate a random connector identifier from the system's source of randomness.

    pub fn random_id() -> ConnectorId {

        type Bytes8 = [u8; std::mem::size_of::<ConnectorId>()];

        unsafe {

            let mut bytes = std::mem::MaybeUninit::<Bytes8>::uninit();

            // getrandom is the canonical crate for a small, secure rng

            getrandom::getrandom(&mut *bytes.as_mut_ptr()).unwrap();

            // safe! representations of all valid Byte8 values are valid ConnectorId values

            std::mem::transmute::<_, _>(bytes.assume_init())

        }

    }

    /// Returns true iff the connector is in connected state, i.e., it's setup phase is complete,

    /// and it is ready to participate in synchronous rounds of communication.

    /// Enables the connector's current logger to be swapped out for another

    /// Access the connector's current logger

    /// Create a new synchronous channel, returning its ends as a pair of ports,

    /// with polarity output, input respectively. Available during either setup/communication phase.

    /// # Panics

    /// This function panics if the connector's (large) port id space is exhausted.

    /// Instantiates a new component for the connector runtime to manage, and passing

    /// the given set of ports from the interface of the native component, to that of the

    /// newly created component (passing their ownership).

    /// # Errors

    /// Error is returned if the moved ports are not owned by the native component,

    /// if the given component name is not defined in the connector's protocol,

    /// the given sequence of ports contains a duplicate port,

    /// or if the component is unfit for instantiation with the given port sequence.

    /// # Panics

    /// This function panics if the connector's (large) component id space is exhausted.

        if let Some(port) = duplicate_port(ports) {

            return Err(Ace::DuplicatePort(port));

        }

    pub(crate) fn union_with(&self, other: &Self) -> Option<Self> {

    pub(crate) fn query(&self, var: SpecVar) -> Option<SpecVal> {

    /// Create a new connector structure with the given protocol description (via Arc to facilitate sharing).

    /// The resulting connector will start in the setup phase, and cannot be used for communication until the

    /// `connect` procedure completes.

    /// # Safety

    /// The correctness of the system's underlying distributed algorithms requires that no two

    /// connectors have the same ID. If the user does not know the identifiers of other connectors in the

    /// system, it is advised to guess it using Connector::random_id (relying on the exceptionally low probability of an error).

    /// Sessions with duplicate connector identifiers will not result in any memory unsafety, but cannot be guaranteed

    /// to preserve their configured protocols.

    /// Fortunately, in most realistic cases, the presence of duplicate connector identifiers will result in an

    /// error during `connect`, observed as a peer misbehaving.

    /// Adds a "dangling" port to the connector in the setup phase,

    /// to be formed into channel during the connect procedure with the given

    /// transport layer information.

    /// Finalizes the connector's setup procedure and forms a distributed system with

    /// all other connectors reachable through network channels. This procedure represents

    /// a synchronization barrier, and upon successful return, the connector can no longer add new network ports,

    /// but is ready to begin the first communication round.

    /// Initially, the connector has a singleton set of _batches_, the only element of which is empty.

    /// This single element starts off selected. The selected batch is modified with `put` and `get`,

    /// and new batches are added and selected with `next_batch`. See `sync` for an explanation of the

    /// purpose of these batches.

                if(fires(b)) put(b, m);

        new replicator(a, d, f);

        new replicator(g, t, h);

        new lossy(e, l);

        new lossy(i, j);

        new replicator(m, b, p);

        new replicator(k, n, c);