Crate portus

Expand description

Welcome to CCP.

This crate, portus, implements a CCP. This includes:

An interface definition for external types wishing to implement congestion control algorithms (CongAlg).
A compiler for datapath programs.
An IPC and serialization layer for communicating with libccp-compliant datapaths.

The entry points into portus are run and spawn, which start the CCP algorithm runtime. There is also the convenience macro start.

The runtime listens for datapath messages and dispatches calls to the appropriate congestion control methods.

Example

The following congestion control algorithm sets the congestion window to 42, and prints the minimum RTT observed over 42 millisecond intervals.

use std::collections::HashMap;
use portus::{CongAlg, Flow, Datapath, DatapathInfo, DatapathTrait, Report};
use portus::ipc::Ipc;
use portus::lang::Scope;
use portus::lang::Bin;

#[derive(Clone, Default)]
struct MyCongestionControlAlgorithm(Scope);

impl<I: Ipc> CongAlg<I> for MyCongestionControlAlgorithm {
    type Flow = Self;

    fn name() -> &'static str {
        "My congestion control algorithm"
    }
    fn datapath_programs(&self) -> HashMap<&'static str, String> {
        let mut h = HashMap::default();
        h.insert(
            "MyProgram", "
                (def (Report
                    (volatile minrtt +infinity)
                ))
                (when true
                    (:= Report.minrtt (min Report.minrtt Flow.rtt_sample_us))
                )
                (when (> Micros 42000)
                    (report)
                    (reset)
                )
            ".to_owned(),
        );
        h
    }
    fn new_flow(&self, mut control: Datapath<I>, info: DatapathInfo) -> Self::Flow {
        let sc = control.set_program("MyProgram", None).unwrap();
        MyCongestionControlAlgorithm(sc)
    }
}
impl Flow for MyCongestionControlAlgorithm {
    fn on_report(&mut self, sock_id: u32, m: Report) {
        println!("minrtt: {:?}", m.get_field("Report.minrtt", &self.0).unwrap());
    }
}

Modules

algs

Helper methods for making algorithm binaries.

ipc

A library wrapping various IPC mechanisms with a datagram-oriented messaging layer. This is how CCP communicates with the datapath.

lang

The datapath program compiler.

serialize

Serialization library for communicating with libccp in the datapath.

test_helper

Helper type for writing unit tests.

Macros

check_msg

Generates a test which serializes and deserializes a message and verifies the message is unchanged.

start

Convenience macro for starting the portus runtime in the common single-algorithm case. The 3-argument form will use blocking IPC sockets. Arguments are:

Structs

CCPHandle

A handle to manage running instances of the CCP execution loop.

Datapath

A collection of methods to interact with the datapath.

DatapathInfo

The set of information passed by the datapath to CCP when a connection starts. It includes a unique 5-tuple (CCP socket id + source and destination IP and port), the initial congestion window (init_cwnd), and flow MSS.

Error

CCP custom error type.

Contains the values of the pre-defined Report struct from the fold function. Use get_field to query its values using the names defined in the fold function.

RunBuilder

Main execution loop of CCP for the static pipeline use case. The run method blocks ‘forever’; it only returns in two cases:

Spawn

StaleProgramError

Traits

CongAlg

implement this trait, portus::CongAlgBuilder and portus::Flow to define a ccp congestion control algorithm.

CongAlgBuilder

Tell portus how to construct instances of your impl [portus::CongAlg].

DatapathTrait

A collection of methods to interact with the datapath.

Flow

Implement this trait, portus::CongAlg, and portus::CongAlgBuilder to define a CCP congestion control algorithm.

Type Definitions

Result

CCP custom Result type, using Error as the Err type.

Attribute Macros

register_ccp_alg