Comments describing the packet structures for pipes.

1 files changed, 30 insertions, 16 deletions

diff --git a/src/libcore/pipes.rs b/src/libcore/pipes.rs
index 1fcebe43221..6a4c09f8473 100644
--- a/src/libcore/pipes.rs
+++ b/src/libcore/pipes.rs
@@ -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
 
-
-
-## 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 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.
+
+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.
 
 */