udp

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.

type struct Name {
    field: Type;
    method(&this) -> Ret { ... }
}

A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.

primitive i32

32-bit signed integer.

static name(param: Type) -> Ret { ... }

A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.

static UdpSocket::bind(local: SocketAddr) -> Result<UdpSocket, IoError>

Open a datagram socket and bind it to local. Use SocketAddr::any_v4(port) to receive on every interface or localhost_v4(port) for loopback. Pass port 0 to let the kernel pick an ephemeral port, then read it back with local_addr.

type struct SocketAddr {
    ip: IpAddr;
    port: u16;
}

SocketAddr: (IP, port).

type enum Result<T, E> {
    Ok(T);
    Err(E);
}

Result: a value that may be an error.

static UdpSocket::unbound() -> Result<UdpSocket, IoError>

Open an unbound datagram socket. The kernel assigns a local address lazily on the first send / connect. Handy for a pure client that only ever talks to one peer.

static UdpSocket::from_fd(sock: i32) -> UdpSocket

Wrap a raw file descriptor. The caller transfers ownership; drop will close it. Used by the futures below to leave a closed placeholder behind while one of them owns the real socket.

UdpSocket::raw_fd(&this) -> i32

Borrow the underlying file descriptor without transferring ownership. The UdpSocket still closes it on drop.

&this
mut &this
this

The receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.

UdpSocket::connect(mut &this, remote: SocketAddr) -> Result<(), IoError>

Pin a default peer. After this, UdpSend/UdpRecv talk to remote and the kernel filters incoming datagrams to that source. Does not exchange packets - UDP connect is local bookkeeping only, so it cannot block and stays a plain call.

mut &this
mut &Type

An exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.

primitive ()

The unit type: a value that carries no information, and the empty tuple. Distinct from void, which is the absence of a value - Result<(), E> succeeds with nothing to return. 0 bytes.

UdpSocket::local_addr(&this) -> Result<SocketAddr, IoError>

The local address the socket is bound to. After bind(.., 0) this reports the kernel-assigned ephemeral port - the only way to learn it.

UdpSocket::set_broadcast(mut &this, on: boolean) -> Result<(), IoError>

Allow sending to the broadcast address. Off by default; the kernel rejects broadcast sends without it (EACCES).

primitive boolean

true / false. Not interchangeable with integers. 1 byte.

UdpSocket::set_nonblocking(mut &this, on: boolean) -> Result<(), IoError>

Put the socket in non-blocking mode, where a send or receive reports WouldBlock instead of sleeping the calling thread. bind and unbound already do this; it is exposed for a descriptor adopted through from_fd, which arrives in an unknown mode.

type struct UdpSendTo {
    socket: UdpSocket;
    buf: Array<u8>;
    dest: SocketAddr;
    rt: Reactor*;
}

Send one datagram to dest. Completes with the number of bytes the kernel accepted; a partial datagram is never sent, so that is the whole buffer on success. The buffer comes back untouched.

type struct Array<T, A = GlobalAlloc> where A: Allocator {
    ptr: T*;
    length: i64;
    capacity: i64;
    alloc: A;
}

Array<T, A>: growable, heap-backed, contiguous sequence.

primitive u8

8-bit unsigned integer.

type struct Reactor {
    mtx: [u8;
    40];
    buckets: [Registration*;
    64];
    poll_h: i64;
    kick_h: i64;
    aux_h: i64;
    shutdown: Atomic<u8>;
    thread: u64;
    timers: Timer*;
    // … 1 more
}

The I/O readiness driver for one Executor. Heap-allocated: worker threads and parked futures hold raw pointers to it, and the backend hands the OS interior addresses, so it must not move.

static UdpSendTo::start(socket: UdpSocket, buf: Array<u8>, dest: SocketAddr) -> UdpSendTo

Begin a send of every byte in buf to dest - socket and buffer both owned by this future until it completes.

type struct UdpSendTo {
    socket: UdpSocket;
    buf: Array<u8>;
    dest: SocketAddr;
    rt: Reactor*;
}

Send one datagram to dest. Completes with the number of bytes the kernel accepted; a partial datagram is never sent, so that is the whole buffer on success. The buffer comes back untouched.

type struct UdpSend {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Send one datagram on a connected socket. Fails NotConnected if no default peer was pinned. Owns the socket and the buffer exactly as UdpSendTo does.

static UdpSend::start(socket: UdpSocket, buf: Array<u8>) -> UdpSend

Begin a send of every byte in buf on the socket's pinned peer.

type struct UdpSend {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Send one datagram on a connected socket. Fails NotConnected if no default peer was pinned. Owns the socket and the buffer exactly as UdpSendTo does.

type struct UdpRecvFrom {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Receive one datagram, completing with the byte count and the peer that sent it. A datagram longer than the buffer is truncated (the tail is discarded - POSIX UDP semantics).

static UdpRecvFrom::start(socket: UdpSocket, buf: Array<u8>) -> UdpRecvFrom

Begin a receive on socket, filling buf - both owned by this future until it completes.

type struct UdpRecvFrom {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Receive one datagram, completing with the byte count and the peer that sent it. A datagram longer than the buffer is truncated (the tail is discarded - POSIX UDP semantics).

type struct UdpRecv {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Receive on a connected socket, dropping the peer address - it can only be the connected peer. Truncates an oversized datagram, as UdpRecvFrom does.

static UdpRecv::start(socket: UdpSocket, buf: Array<u8>) -> UdpRecv

Begin a receive on socket, filling buf.

type struct UdpRecv {
    socket: UdpSocket;
    buf: Array<u8>;
    rt: Reactor*;
}

Receive on a connected socket, dropping the peer address - it can only be the connected peer. Truncates an oversized datagram, as UdpRecvFrom does.

type struct UdpIo {
    socket: UdpSocket;
    buf: Array<u8>;
    result: Result<u64, IoError>;
}

The outcome of a send, or of a receive on a connected socket: the socket handed back, the buffer, and how many bytes moved (or why none did).

primitive u64

64-bit unsigned integer.

UdpIo::take_socket(mut &this) -> UdpSocket

Take the socket back, so the next operation can be started on it. Calling it twice yields a closed socket the second time.

UdpIo::take_buf(mut &this) -> Array<u8>

Take the buffer back. After a receive it holds exactly the bytes of the datagram that arrived; after a send it is untouched, so the caller still has what it sent. Calling it twice yields an empty buffer.

UdpIo::outcome(&this) -> Result<u64, IoError>

How many bytes moved, or why none did.

type struct UdpReceived {
    socket: UdpSocket;
    buf: Array<u8>;
    result: Result<(u64, SocketAddr), IoError>;
}

The outcome of a UdpRecvFrom: as UdpIo, plus the peer that sent the datagram. A separate type rather than an optional field on UdpIo because a peer address is either always meaningful or never so, and a slot that is only sometimes filled is the kind of thing callers read anyway.

UdpReceived::outcome(&this) -> Result<(u64, SocketAddr), IoError>

The byte count and the sender, or why no datagram arrived.

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).

namespace std;

std: the Cryo standard library.

namespace std::net;

net: network primitives + HTTP.

namespace std::net::socket;

net::socket: transport-layer sockets.

namespace std::net::socket::udp;

UDP sockets.

static UdpSocket::bind(local: SocketAddr) -> Result<UdpSocket, IoError>

Open a datagram socket and bind it to local. Use SocketAddr::any_v4(port) to receive on every interface or localhost_v4(port) for loopback. Pass port 0 to let the kernel pick an ephemeral port, then read it back with local_addr.

static UdpSocket::unbound() -> Result<UdpSocket, IoError>

Open an unbound datagram socket. The kernel assigns a local address lazily on the first send / connect. Handy for a pure client that only ever talks to one peer.

UdpSocket::connect(mut &this, remote: SocketAddr) -> Result<(), IoError>

Pin a default peer. After this, UdpSend/UdpRecv talk to remote and the kernel filters incoming datagrams to that source. Does not exchange packets - UDP connect is local bookkeeping only, so it cannot block and stays a plain call.

UdpSocket::drop(mut &this) -> void

via trait Drop

Close the socket. Ownership obligation: every UdpSocket must have drop called before going out of scope.

static SocketAddr::any_v4(port: u16) -> SocketAddr

0.0.0.0:port: bind on every IPv4 interface.

UdpSocket::local_addr(&this) -> Result<SocketAddr, IoError>

The local address the socket is bound to. After bind(.., 0) this reports the kernel-assigned ephemeral port - the only way to learn it.

static UdpSocket::from_fd(sock: i32) -> UdpSocket

Wrap a raw file descriptor. The caller transfers ownership; drop will close it. Used by the futures below to leave a closed placeholder behind while one of them owns the real socket.

UdpSocket::raw_fd(&this) -> i32

Borrow the underlying file descriptor without transferring ownership. The UdpSocket still closes it on drop.

start..end

A half-open range - start up to but excluding end - and sugar for Range::new(start, end): an iterator usable in for, and an ordinary value anywhere else. It binds looser than arithmetic, so a..b + 1 is a..(b + 1).

UdpSocket::set_broadcast(mut &this, on: boolean) -> Result<(), IoError>

Allow sending to the broadcast address. Off by default; the kernel rejects broadcast sends without it (EACCES).

UdpSocket::set_nonblocking(mut &this, on: boolean) -> Result<(), IoError>

Put the socket in non-blocking mode, where a send or receive reports WouldBlock instead of sleeping the calling thread. bind and unbound already do this; it is exposed for a descriptor adopted through from_fd, which arrives in an unknown mode.

static UdpSendTo::start(socket: UdpSocket, buf: Array<u8>, dest: SocketAddr) -> UdpSendTo

Begin a send of every byte in buf to dest - socket and buffer both owned by this future until it completes.

type struct UdpIo {
    socket: UdpSocket;
    buf: Array<u8>;
    result: Result<u64, IoError>;
}

The outcome of a send, or of a receive on a connected socket: the socket handed back, the buffer, and how many bytes moved (or why none did).

type struct UdpReceived {
    socket: UdpSocket;
    buf: Array<u8>;
    result: Result<(u64, SocketAddr), IoError>;
}

The outcome of a UdpRecvFrom: as UdpIo, plus the peer that sent the datagram. A separate type rather than an optional field on UdpIo because a peer address is either always meaningful or never so, and a slot that is only sometimes filled is the kind of thing callers read anyway.

UdpIo::take_socket(mut &this) -> UdpSocket

Take the socket back, so the next operation can be started on it. Calling it twice yields a closed socket the second time.

UdpIo::take_buf(mut &this) -> Array<u8>

Take the buffer back. After a receive it holds exactly the bytes of the datagram that arrived; after a send it is untouched, so the caller still has what it sent. Calling it twice yields an empty buffer.

UdpIo::outcome(&this) -> Result<u64, IoError>

How many bytes moved, or why none did.

implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }

Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.

implement trait Trait for Type { ... }

Introduces a trait implementation: the block supplies, for one concrete type, the method bodies the trait requires.

type trait Future {
    type Output;
    poll(mut &this, cx: Context*) -> Poll<This::Output>;
}

An asynchronous computation. poll drives it one step: Ready(v) when the value is available, Pending when it is not yet (the future has arranged, via cx's waker, to be polled again later).

implement trait Trait for Type { ... }

Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.

type trait Drop {
    drop(mut &this) -> void;
}

Drop: explicit destructor.