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.
RecvPacket
- Represents the receive end of a pipeSendPacket
- The sending end of a piperust_task
Buffer
BufferHeader
Packet
PacketHeader
RecvPacketBuffered
SendPacketBuffered
HasBuffer
Selectable
of ::std::cmp::Eq for State
- Automatically derived.for PacketHeader
of HasBuffer for Packet<T> where <T: Send>
of Drop for BufferResource<T> where <T>
of Drop for SendPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>
for SendPacketBuffered<T, Tbuffer> where <T, Tbuffer>
of Drop for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>
for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>
of Selectable for RecvPacketBuffered<T, Tbuffer> where <T: Send, Tbuffer: Send>
of Selectable for *mut PacketHeader
BufferHeader
PacketHeader
RecvPacket
RecvPacketBuffered
SendPacket
SendPacketBuffered
entangle
entangle_buffer
get_buffer
mk_packet
packet
peek
- Returns true if messages are available.recv
- Receives a message from a pipe.select
- Waits on a set of endpointsselect2
- Receives a message from one of two endpoints.select2i
- Returns 0 or 1 depending on which endpoint is ready to receiveselecti
- Returns the index of an endpoint that is ready to receive.send
swap_task
try_recv
- Attempts to receive a message from a pipe.wait_many
- Returns when one of the packet headers reports data is available.pipes::rt
pipes::rustrt
RecvPacket
type RecvPacket<T> = RecvPacketBuffered<T, Packet<T>>
Represents the receive end of a pipe. It can receive exactly one message.
SendPacket
type SendPacket<T> = SendPacketBuffered<T, Packet<T>>
The sending end of a pipe. It can be used to send exactly one message.
rust_task
type rust_task = libc::c_void
Buffer
pub struct Buffer<T> {
header: BufferHeader,
data: T,
}
BufferHeader
pub struct BufferHeader {
ref_count: int,
}
Packet
pub struct Packet<T> {
header: PacketHeader,
payload: Option<T>,
}
PacketHeader
pub struct PacketHeader {
state: State,
blocked_task: *rust_task,
buffer: *libc::c_void,
}
RecvPacketBuffered
pub struct RecvPacketBuffered<T, Tbuffer> {
p: Option<*mut Packet<T>>,
buffer: Option<BufferResource<Tbuffer>>,
}
SendPacketBuffered
pub struct SendPacketBuffered<T, Tbuffer> {
p: Option<*mut Packet<T>>,
buffer: Option<BufferResource<Tbuffer>>,
}
HasBuffer
set_buffer
fn set_buffer(&mut self, b: *libc::c_void)
Selectable
header
fn header(&mut self) -> *mut PacketHeader
::std::cmp::Eq
for State
Automatically derived.
eq
fn eq(&self, __arg_0: &State) -> ::bool
ne
fn ne(&self, __arg_0: &State) -> ::bool
PacketHeader
mark_blocked
unsafe fn mark_blocked(&mut self, this: *rust_task) -> State
unblock
unsafe fn unblock(&mut self)
buf_header
unsafe fn buf_header(&mut self) -> ~BufferHeader
set_buffer
fn set_buffer<T: Send>(&mut self, b: ~Buffer<T>)
HasBuffer
for Packet<T>
where <T: Send>
set_buffer
fn set_buffer(&mut self, b: *libc::c_void)
Drop
for BufferResource<T>
where <T>
drop
fn drop(&self)
Drop
for SendPacketBuffered<T, Tbuffer>
where <T: Send, Tbuffer: Send>
drop
fn drop(&self)
SendPacketBuffered<T, Tbuffer>
where <T, Tbuffer>
unwrap
fn unwrap(&mut self) -> *mut Packet<T>
header
fn header(&mut self) -> *mut PacketHeader
reuse_buffer
fn reuse_buffer(&mut self) -> BufferResource<Tbuffer>
Drop
for RecvPacketBuffered<T, Tbuffer>
where <T: Send, Tbuffer: Send>
drop
fn drop(&self)
RecvPacketBuffered<T, Tbuffer>
where <T: Send, Tbuffer: Send>
unwrap
fn unwrap(&mut self) -> *mut Packet<T>
reuse_buffer
fn reuse_buffer(&mut self) -> BufferResource<Tbuffer>
Selectable
for RecvPacketBuffered<T, Tbuffer>
where <T: Send, Tbuffer: Send>
header
fn header(&mut self) -> *mut PacketHeader
Selectable
for *mut PacketHeader
header
fn header(&mut self) -> *mut PacketHeader
BufferHeader
fn BufferHeader() -> BufferHeader
PacketHeader
fn PacketHeader() -> PacketHeader
RecvPacket
fn RecvPacket<T>(p: *mut Packet<T>) -> RecvPacket<T>
RecvPacketBuffered
fn RecvPacketBuffered<T, Tbuffer>(p: *mut Packet<T>) ->
RecvPacketBuffered<T, Tbuffer>
SendPacket
fn SendPacket<T>(p: *mut Packet<T>) -> SendPacket<T>
SendPacketBuffered
fn SendPacketBuffered<T, Tbuffer>(p: *mut Packet<T>) ->
SendPacketBuffered<T, Tbuffer>
entangle
fn entangle<T>() -> (RecvPacket<T>, SendPacket<T>)
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>)
get_buffer
unsafe fn get_buffer<T>(p: *mut PacketHeader) -> ~Buffer<T>
mk_packet
fn mk_packet<T: Send>() -> Packet<T>
packet
fn packet<T>() -> *mut Packet<T>
peek
fn peek<T: Send, Tb: Send>(p: &mut RecvPacketBuffered<T, Tb>) -> bool
Returns true if messages are available.
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.
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.
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
.
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
selecti
fn selecti<T: Selectable>(endpoints: &mut [T]) -> uint
Returns the index of an endpoint that is ready to receive.
send
fn send<T, Tbuffer>(mut p: SendPacketBuffered<T, Tbuffer>, payload: T) -> bool
swap_task
fn swap_task(dst: &mut *rust_task, src: *rust_task) -> *rust_task
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.
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.