crate-type = [

	"rlib", # for use as a Rust dependency. 

	"cdylib" # for FFI use, typically C.

]

ffi_pseudo_socket_api = ["ffi", "libc", "os_socketaddr"]# see src/ffi/pseudo_socket_api.rs.

This library provides connectors as a generalization of sockets for use in communication over the internet. This repository is one of the deliverables of the [Reowolf project](https://nlnet.nl/project/Reowolf/) funded by the NLNet foundation.

1. Install the latest stable Rust toolchain (`rustup install stable`) using the [rustup](https://rustup.rs/) CLI tool, available for most platforms.

1. Have `cargo` (the Rust language package manager) download source dependencies, and compile the library with release-level optimizations with `cargo build --release`: 

	- The resulting dylib can be found in `./target/release/`, to be used with the header file: `./reowolf.h`.

	- *Note*: A list of immediate ancestor dependencies is visible in `./Cargo.toml`.

	- *Note*: Run `cargo test --release` to run unit tests with release-level optimizations.

## Using the library

- The library may be used as a Rust dependency by adding it as a git dependency, i.e., by adding line `reowolf_rs = { git = "https://scm.cwi.nl/FM/reowolf" }` to downstream crate's manifest file, `Cargo.toml`.

- The library may be used as a dynamically-linked library using its C ABI as the cdylib written to `./target/release` when compiled with release optimizations, in combination to the header file `./reowolf.h`.

- When compiled on Linux, the compiled library will include definitions of pseudo-socket procedures declared in `./pseudo-socket.h` when compiled with `cargo build --release --features ffi_pseudo_socket_api`. The added functionality is only needed when requiring that connectors expose a socket-like API.

## Examples

The `examples` directory contains example usages of connectors for message passing over the internet. The programs within require that the library is compiled as a dylib (see above).

# Examples

This directory contains a set of programs for demonstrating the use of connectors for communications over the internet.

## Setting up and running

First, ensure that the Reowolf has been compiled, such that a dylib is present in `reowolf/target/release/`; see the parent directory for instructions on compiling the library.

The examples are designed to be run with the examples folder as your working directory (`reowolf/examples`), containing a local copy of the dylic. Two convenience scripts are made available for copying the library: `cpy_dll.sh` and `cpy_so.sh` for platforms Linux and Windows respectively.

Compiling the example programs is done using Python 3, with `python3 ./make.py`, which will crawl the example directory's children and compiling any C source files. 

## Groups of examples and takeaways

### Incremental Connector API examples

The examples contained within directories with names prefixed with `incremental_` demonstrate usage of the connector API. This set of examples is characterized by each example being self-contained, designed to be run in isolation. The examples are best understood when read in the order of their directories' names (from 1 onward), as they demonstrate the functionality of the connector API starting from the most (trivially) simple connectors, to more complex connectors incorporating multiple network channels and components.

Each example source file is prefixed by a multi-line comment, explaining what a reader is intended to take away from the example.

### Presentation examples

The examples contained within directories with names matching `pres_` are designed to accompany the Reowolf demonstration slides (inclusion here TODO).

Examples include interactions whose distributed sessions span multiple source files. What follows is a list of the sessions' consituent programs, along with what the session intends to demonstrate

1. {pres_1/amy, pres_1/bob}: Connectors can be used to transmit messages over the internet in a fashion comparable to that of UDP sockets.

2. {pres_1/amy, pres_2/bob}: The protocol descriptions used to configure components are loaded and parsed at runtime. Consequently, changing these descriptions can change the behavior of the system without recompiling any of the constituent programs.

2. {pres_3/amy, pres_3/bob}: *Atomicity*. Message exchange actions are grouped into synchronous interactions. Actions occur with observable effects IFF their interactions are well-formed, and complete successfully. For example, a put succeeds IFF its accompanying get succeeds.

2. {pres_3/amy, pres_4/bob}: *Nondeterminism*. Programs/components can express flexibility by providing mutually-exclusive firing patterns on their ports, as a nondeterministic choice. Which (if any) choice occurs can be determined after synchronization by inspecting the return value of `connector_sync`. Atomicity + Nondeterminism = Specialization of behavior.

2. {pres_5/amy, pres_5/bob}: When no synchronous interaction is found before some consituent program times out, the system RECOVERS to the synchronous state at the start of the round, allowing components to try again.

### Interoperability examples

The examples contained within directories with names matching `interop_` demonstrate the use of different APIs for communication over UDP channels. The three given programs are intended to be run together, each as its own process.

Each example source file is prefixed by a multi-line comment, explaining what a reader is intended to take away from the example.

/* This example demonstrates:

- how protocol description structures are created and destroyed

- how connectors are created and destroyed

- there are procedures allowing for debugging the states of connectors

*/

/* This example demonstrates:

- protocol descriptions are parsed from ascii text expressed in Reowolf's protocol language, PDL

- protocol descriptions load their PDL at runtime; component's definitions can be changed without recompiling the main program

*/

/* This example demonstrates:

- Connectors begin in a "setup" state, which is existing with `connector_connect`

*/

/* This example demonstrates:

- Connectors in the setup state can add new channels by creating port pairs

*/

/* This example demonstrates:

- After connecting, ports can exchange messages

- Message exchange is conducted in two phases:

	1. preparing with `connector_put`, `connector_get`, and

	2. completing with `connector_sync`.

	This paradigm is similar to that for sockets in non-blocking mode.

- The connector stores messages received during sync. they can be inspected using `connector_gotten_bytes`.

- Ports created using `connector_add_port_pair` behave as a synchronous channel; messages sent in one end are received at the other.

*/

	connector_sync(c, -1); // -1 means infinite timeout duration

/* This example demonstrates:

- Synchronized PUTs and GETs always succeed together.

- Attemping to put without a corresponding GET results in `connector_sync` failing at runtime.

*/

	int err = connector_sync(c, 5000); // 5000 means 5000millisec timeout duration

/* This example demonstrates:

- Synchronous rounds that fail result in RECOVERY; no messages are sent or received.

*/

/* This example demonstrates:

- Synchronous channels can span the network if created by pairs of `connector_add_net_port` calls,

	each binding a port to the same address, with complementary polarities.

- Ports created this way have two notions of polarity:

	- (port) Polarity in {Putter, Getter}:

		- Putter => resulting port can `connector_put`,

		- Getter => resulting port can `connector_get`,

	- Endpoint Polarity in {Active, Passive}:

		- Passive => underlying transport socket will `bind` to the given address,

		- Active  => underlying transport socket will `connect` to the given address,

*/

	FfiSocketAddr addr = {{127, 0, 0, 1}, 8000}; // ipv4 127.0.0.1 (localhost) transport port 8000

/* This example demonstrates:

- Once created, ports transport messages regardless of whether

	they were created with `connector_add_port_pair` or `connector_add_net_port`.

*/

	FfiSocketAddr addr = {{127, 0, 0, 1}, 8000};

/* This example demonstrates:

- conventional UDP socket API can be used in a connection-oriented fashion

    - first setup with `bind` and `connect`

    - henceforth communicating with connected peer using `send` and `recv` in blocking mode.

*/

/* This example demonstrates:

- Reowolf's pseudo-socket API mimics the API of UDP sockets

- This example corresponds closely with that of the socket API, differing only in:

    1. an added import of the pseudo-socket header file

    2. (pseudo-)socket operations' identifiers are prefixed with `rw_` (short for "Reowolf"). 

*/

/* This example demonstrates:

- connector API can create UDP mediator components, each given a BIND and CONNECT socket address,

  which communicates via a returned putter and getter port pair.

- messages passed to the UDP mediator are forwarded as UDP datagrams into the network.

*/

	FfiSocketAddr addr = {{127, 0, 0, 1}, 8000};