From 6dcd0a9b5e8b45262e3225ddff62d0a1098006ca Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Wed, 14 Sep 2011 14:48:40 -0700 Subject: [PATCH] Remove mention of port, chan and task *types*, as they're not just library-provided. Move some text about channels into the comm section. --- doc/rust.texi | 108 +++++--------------------------------------------- 1 file changed, 11 insertions(+), 97 deletions(-) diff --git a/doc/rust.texi b/doc/rust.texi index 2dce38ecd31..db6421bf147 100644 --- a/doc/rust.texi +++ b/doc/rust.texi @@ -1474,6 +1474,15 @@ Each channel is bound to a port when the channel is constructed, so the destination port for a channel must exist before the channel itself. A channel cannot be rebound to a different port from the one it was constructed with. +Channels are weak: a channel does not keep the port it is bound to +alive. Ports are owned by their allocating task and cannot be sent over +channels; if a task dies its ports die with it, and all channels bound to +those ports no longer function. Messages sent to a channel connected to a dead +port will be dropped. + +Channels are immutable types with meaning known to the runtime; channels can +be sent over channels. + Many channels can be bound to the same port, but each channel is bound to a single port. In other words, channels and ports exist in an N:1 relationship, N channels to 1 port. @footnote{It may help to remember nautical terminology @@ -1482,20 +1491,14 @@ channels -- may lead to the same port.} Each port and channel can carry only one type of message. The message type is encoded as a parameter of the channel or port type. The message type of a -channel is equal to the message type of the port it is bound to. +channel is equal to the message type of the port it is bound to. The types of +messages must be of @emph{unique} kind. Messages are generally sent asynchronously, with optional rate-limiting on the transmit side. A channel contains a message queue and asynchronously sending a message merely inserts it into the sending channel's queue; message receipt is the responsibility of the receiving task. -Queued messages in channels are charged to the @emph{sending} task. If too -many messages are queued for transmission from a single sending task, without -being received by a receiving task, the sending task may exceed its memory -budget, which causes a run-time signal. To help control this possibility, a -semi-synchronous send operation is possible, which blocks until there is room -in the existing queue before sending send. - Messages are sent on channels and received on ports using standard library functions. @@ -2166,9 +2169,6 @@ Rust; they cannot be used as user-defined identifiers in any context. * Ref.Type.Tag:: Disjoint unions of heterogeneous types. * Ref.Type.Fn:: Subroutine types. * Ref.Type.Iter:: Scoped coroutine types. -* Ref.Type.Port:: Unique inter-task message-receipt endpoints. -* Ref.Type.Chan:: Copyable inter-task message-send capabilities. -* Ref.Type.Task:: General coroutine-instance types. * Ref.Type.Obj:: Abstract types. * Ref.Type.Constr:: Constrained types. * Ref.Type.Type:: Types describing types. @@ -2472,92 +2472,6 @@ for each (i: int in range(5,7)) @{ @} @end example - -@node Ref.Type.Port -@subsection Ref.Type.Port -@cindex Port types -@cindex Communication - -The port type-constructor @code{port} forms types that describe ports. A port -is the @emph{receiving end} of a typed, asynchronous, simplex inter-task -communication facility. @xref{Ref.Task.Comm}. A @code{port} type takes a -single type parameter, denoting the type of value that can be received from a -@code{port} value of that type. - -Ports are modeled as stateful native types, with built-in meaning to the -language. They cannot be transmitted over channels or otherwise replicated, -and are always local to the task that creates them. - -Ports (like channels) can only be carry types of unique kind. No shared or -pinned values can pass over a port or channel. - -An example of a @code{port} type: -@example -type svp = port<[str]>; -let p: svp = get_port(); -let v: [str] = p.recv(); -@end example - -@node Ref.Type.Chan -@subsection Ref.Type.Chan -@cindex Channel types -@cindex Communication - -The channel type-constructor @code{chan} forms types that describe channels. A -channel is the @emph{sending end} of a typed, asynchronous, simplex inter-task -communication facility. @xref{Ref.Task.Comm}. A @code{chan} type takes a -single type parameter, denoting the type of value that can be sent to a -channel of that type. - -Channels are immutable, and can be transmitted over channels to other -tasks. They are modeled as immutable native types with built-in meaning to the -language. - -Channels (like ports) can only be carry types of unique kind. No -pinned or shared values can pass over a port or channel. - -When a task sends a message into a channel, the task forms an outgoing queue -associated with that channel. The per-task queue @emph{associated} with a -channel can be indirectly manipulated by the task, but is @emph{not} otherwise -considered ``part of'' to the channel: the queue is ``part of'' the -@emph{sending task}. Sending a channel to another task does not copy the queue -associated with the channel. - -Channels are also @emph{weak}: a channel is directly coupled to a particular -destination port on a particular task, but does not keep that port or task -@emph{alive}. A channel may therefore fail to operate at any moment. If a task -sends a message to a channel that is connected to a nonexistent port, the -message is dropped. - -An example of a @code{chan} type: -@example -type svc = chan<[str]>; -let c: svc = get_chan(); -let v: [str] = ["hello", "world"]; -std::comm::send(c, v); -@end example - -@node Ref.Type.Task -@subsection Ref.Type.Task -@cindex Task type - -The task type @code{task} describes values that are @emph{live -tasks}. - -Tasks form an @emph{ownership tree} in which each task (except the root task) -is directly owned by exactly one parent task. The purpose of a variable of -@code{task} type is to manage the lifecycle of the associated -task. Communication is carried out solely using channels and ports. - -Like ports, tasks are modeled as mutable native types with built-in meaning to -the language. They cannot be transmitted over channels or otherwise -replicated, and are always local to the task that spawns them. - -If all references to a task are dropped (due to the release of any structure -holding those references), the runtime signals the un-referenced task, which -then fails. @xref{Ref.Task.Life}. - - @node Ref.Type.Obj @subsection Ref.Type.Obj @c * Ref.Type.Obj:: Object types.