---

yaml
---
r: 29776
b: refs/heads/incoming
c: 8bb5f07
h: refs/heads/master
v: v3

Author: eholk

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 6e311836140f86582501550da249c1df70427ab4
+refs/heads/incoming: 8bb5f077c4feb6a2a180810fc16c092bf3532f76
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/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.
 
 */