mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Comments describing the packet structures for pipes.

Browse Source
This commit is contained in:
Eric Holk 2012-08-13 10:55:01 -07:00
parent 6e31183614
commit 8bb5f077c4
1 changed files with 28 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
src/libcore/pipes.rs
View File

@ -35,26 +35,40 @@ syntax extension. To see how that works, it is best see comments in
libsyntax/ext/pipes.rs.
This module includes two related pieces of the runtime
implementation. There is support for unbounded and bounded
implementation: support for unbounded and bounded
protocols. The main difference between the two is the type of the
buffer that is carried along in the endpoint data structures.
FIXME (#3072) - This is still incomplete
The heart of the implementation is the packet type. It contains a
header and a payload field. Much of the code in this module deals with
the header field. This is where the synchronization information is
stored. In the case of a bounded protocol, the header also includes a
pointer to the buffer the packet is contained in.
Packets represent a single message in a protocol. The payload field
gets instatiated at the type of the message, which is usually an enum
generated by the pipe compiler. Packets are conceptually single use,
although in bounded protocols they are reused each time around the
loop.
Packets are usually handled through a send_packet_buffered or
recv_packet_buffered object. Each packet is referenced by one
send_packet and one recv_packet, and these wrappers enforce that only
one end can send and only one end can receive. The structs also
include a destructor that marks packets are terminated if the sender
or receiver destroys the object before sending or receiving a value.
## Invariants
This section attempts to document the invariants that must hold to
avoid races. These primarily deal with the state and blocked_task
fields on packet_headers.
1. If the sender reads a some(task) out of blocked_task, then the task
that is pointed there will remain live for any events that the sender
might signal.
2. The sender may only read the blocked_task field if it first ensures
that the packet's state field is blocked.
The *_packet_buffered structs take two type parameters. The first is
the message type for the current packet (or state). The second
represents the type of the whole buffer. For bounded protocols, the
protocol compiler generates a struct with a field for each protocol
state. This generated struct is used as the buffer type parameter. For
unbounded protocols, the buffer is simply one packet, so there is a
shorthand struct called send_packet and recv_packet, where the buffer
type is just `packet<T>`. Using the same underlying structure for both
bounded and unbounded protocols allows for less code duplication.
*/