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 ChanOne

type ChanOne<T: Owned> = oneshot::client::Oneshot<T>

The send end of a oneshot pipe.

Type PortOne

type PortOne<T: Owned> = oneshot::server::Oneshot<T>

The receive end of a oneshot pipe.

Type RecvPacket

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

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

Type SendPacket

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

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

Type SharedChan

type SharedChan<T: Owned> = private::Exclusive<Chan<T>>

A channel that can be shared between many senders.

Enum Chan

An endpoint that can send many messages.

Variants

Enum Port

An endpoint that can receive many messages.

Variants

Struct BufferHeader

pub struct BufferHeader {
    mut ref_count: int,
}

Struct BufferResource

struct BufferResource <T: Owned>{
    buffer: ~Buffer<T>,
}

Struct PacketHeader

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

Struct PortSet

pub struct PortSet <T: Owned>{
    mut ports: ~[pipes::Port<T>],
}

Treat many ports as one.

Struct RecvPacketBuffered

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

Struct SendPacketBuffered

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

Interface GenericChan

A trait for things that can send multiple messages.

Method send

fn send(x: T)

Sends a message.

Interface GenericPort

A trait for things that can receive multiple messages.

Method recv

fn recv() -> T

Receives a message, or fails if the connection closes.

Method try_recv

fn try_recv() -> Option<T>

Receives a message, or returns none if the connection is closed or closes.

Interface GenericSmartChan

Things that can send multiple messages and can detect when the receiver is closed

Method try_send

fn try_send(x: T) -> bool

Sends a message, or report if the receiver has closed the connection.

Interface Peekable

Ports that can peek

Method peek

fn peek() -> bool

Returns true if a message is available

Interface Select2

Receive a message from one of two endpoints.

Method try_select

fn try_select() -> Either<Option<T>, Option<U>>

Receive a message or return None if a connection closes.

Method select

fn select() -> Either<T, U>

Receive a message or fail if a connection closes.

Implementation of Eq for State

Method eq

fn eq(other: &State) -> bool

Method ne

fn ne(other: &State) -> bool

Implementation for PacketHeader

Method mark_blocked

fn mark_blocked(this: *rust_task) -> State

Method unblock

fn unblock()

Method buf_header

fn buf_header() -> ~BufferHeader

Method set_buffer

fn set_buffer<T: Owned>(b: ~Buffer<T>)

Implementation of HasBuffer for Packet<T>

Method set_buffer_

fn set_buffer_(b: *libc::c_void)

Implementation of Peekable<T> for RecvPacketBuffered<T, Tb>

Method peek

fn peek() -> bool

Implementation of Selectable for *PacketHeader

Method header

fn header() -> *PacketHeader

Implementation for SendPacketBuffered<T, Tbuffer>

Method unwrap

fn unwrap() -> *Packet<T>

Method header

fn header() -> *PacketHeader

Method reuse_buffer

fn reuse_buffer() -> BufferResource<Tbuffer>

Implementation for RecvPacketBuffered<T, Tbuffer>

Method unwrap

fn unwrap() -> *Packet<T>

Method reuse_buffer

fn reuse_buffer() -> BufferResource<Tbuffer>

Implementation of Selectable for RecvPacketBuffered<T, Tbuffer>

Method header

fn header() -> *PacketHeader

Implementation of GenericChan<T> for Chan<T>

Method send

fn send(x: T)

Implementation of GenericSmartChan<T> for Chan<T>

Method try_send

fn try_send(x: T) -> bool

Implementation of GenericPort<T> for Port<T>

Method recv

fn recv() -> T

Method try_recv

fn try_recv() -> Option<T>

Implementation of Peekable<T> for Port<T>

Method peek

fn peek() -> bool

Implementation of Selectable for Port<T>

Method header

fn header() -> *PacketHeader

Implementation for PortSet<T>

Method add

fn add(port: pipes::Port<T>)

Method chan

fn chan() -> Chan<T>

Implementation of GenericPort<T> for PortSet<T>

Method try_recv

fn try_recv() -> Option<T>

Method recv

fn recv() -> T

Implementation of Peekable<T> for PortSet<T>

Method peek

fn peek() -> bool

Implementation of GenericChan<T> for SharedChan<T>

Method send

fn send(x: T)

Implementation of GenericSmartChan<T> for SharedChan<T>

Method try_send

fn try_send(x: T) -> bool

Implementation of Select2<T, U> for (Left, Right)

Method select

fn select() -> Either<T, U>

Method try_select

fn try_select() -> Either<Option<T>, Option<U>>

Function BufferHeader

fn BufferHeader() -> BufferHeader

Function BufferResource

fn BufferResource<T: Owned>(b: ~Buffer<T>) -> BufferResource<T>

Function PacketHeader

fn PacketHeader() -> PacketHeader

Function PortSet

fn PortSet<T: Owned>() -> PortSet<T>

Function RecvPacketBuffered

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

Function SendPacketBuffered

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

Function SharedChan

fn SharedChan<T: Owned>(c: Chan<T>) -> SharedChan<T>

Converts a chan into a shared_chan.

Function oneshot

fn oneshot<T: Owned>() -> (ChanOne<T>, PortOne<T>)

Initialiase a (send-endpoint, recv-endpoint) oneshot pipe pair.

Function peek

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

Returns true if messages are available.

Function recv

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

Receives a message from a pipe.

Fails if the sender closes the connection.

Function recv_one

fn recv_one<T: Owned>(port: PortOne<T>) -> T

Receive a message from a oneshot pipe, failing if the connection was closed.

Function select

fn select<T: Owned, Tb: Owned>(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: Owned, Ab: Owned, B: Owned,
           Bb: Owned>(a: RecvPacketBuffered<A, Ab>,
                      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: &A, b: &B) -> Either<(), ()>

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

Function selecti

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

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

Function send_one

fn send_one<T: Owned>(chan: ChanOne<T>, data: T)

Send a message on a oneshot pipe, failing if the connection was closed.

Function spawn_service

fn spawn_service<T: Owned,
                 Tb: Owned>(init:
                                extern fn()
                                    ->
                                        (SendPacketBuffered<T, Tb>,
                                         RecvPacketBuffered<T, Tb>),
                            service: ~fn(v: RecvPacketBuffered<T, Tb>)) ->
 SendPacketBuffered<T, Tb>

Spawn a task to provide a service.

It takes an initialization function that produces a send and receive endpoint. The send endpoint is returned to the caller and the receive endpoint is passed to the new task.

Function spawn_service_recv

fn spawn_service_recv<T: Owned,
                      Tb: Owned>(init:
                                     extern fn()
                                         ->
                                             (RecvPacketBuffered<T, Tb>,
                                              SendPacketBuffered<T, Tb>),
                                 service: ~fn(v: SendPacketBuffered<T, Tb>))
 -> RecvPacketBuffered<T, Tb>

Like spawn_service_recv, but for protocols that start in the receive state.

Function stream

fn stream<T: Owned>() -> (Port<T>, Chan<T>)

Creates a (chan, port) pair.

These allow sending or receiving an unlimited number of messages.

Function try_recv

fn try_recv<T: Owned, Tbuffer: Owned>(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 try_recv_one

fn try_recv_one<T: Owned>(port: PortOne<T>) -> Option<T>

Receive a message from a oneshot pipe unless the connection was closed.

Function try_send_one

fn try_send_one<T: Owned>(chan: ChanOne<T>, data: T) -> bool

Send a message on a oneshot pipe, or return false if the connection was closed.

Function wait_many

fn wait_many<T: Selectable>(pkts: &[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.