From 97aa90d251f6f2a951d01b7d1033bc7a42bf6f69 Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Wed, 7 May 2014 10:40:39 -0700 Subject: [PATCH] spec: several clarifications to language on channels - A channel may be used between any number of goroutines, not just two. - Replace "passing a value" (which is not further defined) by "sending and receiving a value". - Made syntax production more symmetric. - Talk about unbuffered channels before buffered channels. - Clarify what the comma,ok receive values mean (issue 7785). Not a language change. Fixes #7785. LGTM=rsc, r, iant R=r, rsc, iant, ken CC=golang-codereviews https://golang.org/cl/94030045 --- doc/go_spec.html | 72 +++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index 114ceed86f8..2f6fd2b97e8 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1278,20 +1278,23 @@ may be added.

Channel types

-A channel provides a mechanism for two concurrently executing functions -to synchronize execution and communicate by passing a value of a -specified element type. +A channel provides a mechanism for +concurrently executing functions +to communicate by +sending and +receiving +values of a specified element type. The value of an uninitialized channel is nil. 

-ChannelType = ( "chan" [ "<-" ] | "<-" "chan" ) ElementType .
+ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType .

-The <- operator specifies the channel direction, +The optional <- operator specifies the channel direction, send or receive. If no direction is given, the channel is -bi-directional. +bidirectional. A channel may be constrained only to send or only to receive by conversion or assignment.

@@ -1318,7 +1321,7 @@ chan (<-chan int) A new, initialized channel value can be made using the built-in function make, -which takes the channel type and an optional capacity as arguments: +which takes the channel type and an optional capacity as arguments: 

@@ -1326,21 +1329,35 @@ make(chan int, 100)

-The capacity, in number of elements, sets the size of the buffer in the channel. If the -capacity is greater than zero, the channel is asynchronous: communication operations -succeed without blocking if the buffer is not full (sends) or not empty (receives), -and elements are received in the order they are sent. -If the capacity is zero or absent, the communication succeeds only when both a sender and -receiver are ready. +The capacity, in number of elements, sets the size of the buffer in the channel. +If the capacity is zero or absent, the channel is unbuffered and communication +succeeds only when both a sender and receiver are ready. Otherwise, the channel is +buffered and communication operations succeed without blocking if the buffer +is not full (sends) or not empty (receives). A nil channel is never ready for communication.

A channel may be closed with the built-in function -close; the -multi-valued assignment form of the +close. +The multi-valued assignment form of the receive operator -tests whether a channel has been closed. +reports whether a received value was sent before +the channel was closed. +

+ +

+A single channel may be used in +send statements, +receive operations, +and calls to the built-in functions +cap and +len +by any number of goroutines without further synchronization. +Channels act as first-in-first-out queues. +For example, if one goroutine sends values on a channel +and a second goroutine receives them, the values are +received in the order sent.

Properties of types and values

@@ -3389,7 +3406,8 @@ and the type of the receive operation is the element type of the channel. The expression blocks until a value is available. Receiving from a nil channel blocks forever. A receive operation on a closed channel can always proceed -immediately, yielding the element type's zero value. +immediately, yielding the element type's zero value +after any previously sent values have been received. 

@@ -4238,22 +4256,8 @@ A send on a closed channel proceeds by causing a run-
 A send on a nil channel blocks forever.
 

 
-

-Channels act as first-in-first-out queues.
-For example, if a single goroutine sends on a channel values
-that are received by a single goroutine, the values are received in the order sent.
-

-
-

-A single channel may be used for send and receive
-operations and calls to the built-in functions
-cap and
-len
-by any number of goroutines without further synchronization.
-

-
 
-ch <- 3
+ch <- 3  // send value 3 to channel ch
 

 
 
@@ -5383,8 +5387,8 @@ make(T, n, m)    slice      slice of type T with length n and capacity m
 make(T)          map        map of type T
 make(T, n)       map        map of type T with initial space for n elements
 
-make(T)          channel    synchronous channel of type T
-make(T, n)       channel    asynchronous channel of type T, buffer size n
+make(T)          channel    unbuffered channel of type T
+make(T, n)       channel    buffered channel of type T, buffer size n