Runtime support for message passing with protocol enforcement.

Pipes consist of two endpoints. One endpoint can send messages and the other can receive messages. The set of legal messages and which directions they can flow at any given point are determined by a protocol. Below is an example protocol.

proto! pingpong (
    ping: send {
        ping -> pong
    }
    pong: recv {
        pong -> ping
    }
)

The proto! syntax extension will convert this into a module called pingpong, which includes a set of types and functions that can be used to write programs that follow the pingpong protocol.

Type RecvPacket

type RecvPacket<T> = RecvPacketBuffered<T, Packet<T>>

Represents the receive end of a pipe. It can receive exactly one message.

Type SendPacket

type SendPacket<T> = SendPacketBuffered<T, Packet<T>>

The sending end of a pipe. It can be used to send exactly one message.

Type rust_task

type rust_task = libc::c_void

Struct Buffer

pub struct Buffer<T> {
    header: BufferHeader,
    data: T,
}

Struct BufferHeader

pub struct BufferHeader {
    ref_count: int,
}

Struct Packet

pub struct Packet<T> {
    header: PacketHeader,
    payload: Option<T>,
}

Struct PacketHeader

pub struct PacketHeader {
    state: State,
    blocked_task: *rust_task,
    buffer: *libc::c_void,
}

Struct RecvPacketBuffered

pub struct RecvPacketBuffered<T, Tbuffer> {
    p: Option<*mut Packet<T>>,
    buffer: Option<BufferResource<Tbuffer>>,
}

Struct SendPacketBuffered

pub struct SendPacketBuffered<T, Tbuffer> {
    p: Option<*mut Packet<T>>,
    buffer: Option<BufferResource<Tbuffer>>,
}

Trait HasBuffer

Method set_buffer

fn set_buffer(&mut self, b: *libc::c_void)

Trait Selectable

Method header

fn header(&mut self) -> *mut PacketHeader

Implementation of ::std::cmp::Eq for State

Automatically derived.

Method eq

fn eq(&self, __arg_0: &State) -> ::bool

Method ne

fn ne(&self, __arg_0: &State) -> ::bool

Implementation for PacketHeader

Method mark_blocked

unsafe fn mark_blocked(&mut self, this: *rust_task) -> State

Method unblock

unsafe fn unblock(&mut self)

Method buf_header

unsafe fn buf_header(&mut self) -> ~BufferHeader

Method set_buffer

fn set_buffer<T: Send>(&mut self, b: ~Buffer<T>)

Implementation of HasBuffer for Packet<T> where <T: Send>

Method set_buffer

fn set_buffer(&mut self, b: *libc::c_void)

Implementation of Drop for BufferResource<T> where <T>

Method drop

fn drop(&self)

Implementation of Drop for SendPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>

Method drop

fn drop(&self)

Implementation for SendPacketBuffered<T, Tbuffer> where <T, Tbuffer>

Method unwrap

fn unwrap(&mut self) -> *mut Packet<T>

Method header

fn header(&mut self) -> *mut PacketHeader

Method reuse_buffer

fn reuse_buffer(&mut self) -> BufferResource<Tbuffer>

Implementation of Drop for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>

Method drop

fn drop(&self)

Implementation for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>

Method unwrap

fn unwrap(&mut self) -> *mut Packet<T>

Method reuse_buffer

fn reuse_buffer(&mut self) -> BufferResource<Tbuffer>

Implementation of Selectable for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>

Method header

fn header(&mut self) -> *mut PacketHeader

Implementation of Selectable for *mut PacketHeader

Method header

fn header(&mut self) -> *mut PacketHeader

Function BufferHeader

fn BufferHeader() -> BufferHeader

Function PacketHeader

fn PacketHeader() -> PacketHeader

Function RecvPacket

fn RecvPacket<T>(p: *mut Packet<T>) -> RecvPacket<T>

Function RecvPacketBuffered

fn RecvPacketBuffered<T, Tbuffer>(p: *mut Packet<T>) ->
 RecvPacketBuffered<T, Tbuffer>

Function SendPacket

fn SendPacket<T>(p: *mut Packet<T>) -> SendPacket<T>

Function SendPacketBuffered

fn SendPacketBuffered<T, Tbuffer>(p: *mut Packet<T>) ->
 SendPacketBuffered<T, Tbuffer>

Function entangle

fn entangle<T>() -> (RecvPacket<T>, SendPacket<T>)

Function entangle_buffer

fn entangle_buffer<T: Send,
                   Tstart: Send>(mut buffer: ~Buffer<T>,
                                 init:
                                     &fn(*libc::c_void, x: &mut T)
                                         -> *mut Packet<Tstart>) ->
 (RecvPacketBuffered<Tstart, T>, SendPacketBuffered<Tstart, T>)

Function get_buffer

unsafe fn get_buffer<T>(p: *mut PacketHeader) -> ~Buffer<T>

Function mk_packet

fn mk_packet<T: Send>() -> Packet<T>

Function packet

fn packet<T>() -> *mut Packet<T>

Function peek

fn peek<T: Send, Tb: Send>(p: &mut RecvPacketBuffered<T, Tb>) -> bool

Returns true if messages are available.

Function recv

fn recv<T: Send, Tbuffer: Send>(p: RecvPacketBuffered<T, Tbuffer>) -> T

Receives a message from a pipe.

Fails if the sender closes the connection.

Function select

fn select<T: Send, Tb: Send>(mut endpoints: ~[RecvPacketBuffered<T, Tb>]) ->
 (uint, Option<T>, ~[RecvPacketBuffered<T, Tb>])

Waits on a set of endpoints. Returns a message, its index, and a list of the remaining endpoints.

Function select2

fn select2<A: Send, Ab: Send, B: Send,
           Bb: Send>(mut a: RecvPacketBuffered<A, Ab>,
                     mut b: RecvPacketBuffered<B, Bb>) ->
 Either<(Option<A>, RecvPacketBuffered<B, Bb>),
        (RecvPacketBuffered<A, Ab>, Option<B>)>

Receives a message from one of two endpoints.

The return value is left if the first endpoint received something, or right if the second endpoint receives something. In each case, the result includes the other endpoint as well so it can be used again. Below is an example of using select2.

match select2(a, b) {
    left((none, b)) {
        // endpoint a was closed.
    }
    right((a, none)) {
        // endpoint b was closed.
    }
    left((Some(_), b)) {
        // endpoint a received a message
    }
    right(a, Some(_)) {
        // endpoint b received a message.
    }
}

Sometimes messages will be available on both endpoints at once. In this case, select2 may return either left or right.

Function select2i

fn select2i<A: Selectable, B: Selectable>(a: &mut A, b: &mut B) ->
 Either<(), ()>

Returns 0 or 1 depending on which endpoint is ready to receive

Function selecti

fn selecti<T: Selectable>(endpoints: &mut [T]) -> uint

Returns the index of an endpoint that is ready to receive.

Function send

fn send<T, Tbuffer>(mut p: SendPacketBuffered<T, Tbuffer>, payload: T) -> bool

Function swap_task

fn swap_task(dst: &mut *rust_task, src: *rust_task) -> *rust_task

Function try_recv

fn try_recv<T: Send, Tbuffer: Send>(mut p: RecvPacketBuffered<T, Tbuffer>) ->
 Option<T>

Attempts to receive a message from a pipe.

Returns None if the sender has closed the connection without sending a message, or Some(T) if a message was received.

Function wait_many

fn wait_many<T: Selectable>(pkts: &mut [T]) -> uint

Returns when one of the packet headers reports data is available.

This function is primarily intended for building higher level waiting functions, such as select, select2, etc.

It takes a vector slice of packet_headers and returns an index into that vector. The index points to an endpoint that has either been closed by the sender or has a message waiting to be received.