Add documentation for Channel#send and Channel#close (crystal-lang#8346) #8356

lbarasti · 2019-10-20T20:56:27Z

lbarasti · 2019-10-20T21:01:54Z

src/channel.cr

-  # channel.send(1)
+  # spawn do
+  #   channel.send(1)
+  # end


An alternative way to fix the code snippet would be to go buffered

channel = Channel(Int32).new(1) channel.send(42) channel.receive # => 42

lbarasti · 2019-10-20T21:02:36Z

src/channel.cr

@@ -182,13 +191,15 @@ class Channel(T)
  end

  # Receives a value from the channel.
-  # If there is a value waiting, it is returned immediately. Otherwise, this method blocks until a value is sent to the channel.
+  # If there is a value waiting, then it is returned immediately. Otherwise, this method blocks until a value is sent to the channel.


Added then for consistency with the docs above - both are valid, I believe

lbarasti · 2019-10-20T21:03:34Z

src/channel.cr

+  # Closes the channel.
+  # The method prevents any new value from being sent to / received from the channel.
+  # It wakes up any sender / receiver fibers waiting on the channel.
+  # It only has effect *after* any previously enqueued value in the channel has been received, up to the channel's capacity.


I appreciate the wording can be improved, so happy to take suggestions here

I'd probably just say

All items successfully sent to the channel can be received before receive considers the channel closed, but send will consider the channel closed before close returns.

lbarasti · 2019-10-20T21:05:26Z

src/channel.cr

+  # Closes the channel.
+  # The method prevents any new value from being sent to / received from the channel.
+  # It wakes up any sender / receiver fibers waiting on the channel.
+  # It only has effect *after* any previously enqueued value in the channel has been received, up to the channel's capacity.


I would add that calling close on a closed channel does not have any effect, but such behaviour hasn't been documented in the specs, so I'd better add a test too, if we're keen on being explicit on that

I'd document and spec that. You can do that in this PR.

Done:

added to Channel#close docs

Calling `#close` on a closed channel does not have any effect.

Added spec

Channel "does not raise nor change its status when it is closed more than once"

RX14 · 2019-10-29T20:45:39Z

src/channel.cr

@@ -114,6 +114,10 @@ class Channel(T)
    end
  end

+  # Closes the channel.
+  # The method prevents any new value from being sent to / received from the channel.
+  # It wakes up any sender / receiver fibers waiting on the channel.


All fibers blocked in send or receive will recieve Channel::ClosedError?

Exactly, see

spec 1 and spec 2 for #receive

spec for #receive?

spec 1 and spec 2 for #send

I meant to suggest this as a better wording.

will update this later today 👍

@RX14

All fibers blocked in send or receive will receive Channel::ClosedError

is ambiguous in that one might expect to actually receive an object of type ClosedError. I'm opting for

All fibers blocked in send or receive will be awakened with Channel::ClosedError

Let me know what you think

RX14 · 2019-10-29T20:49:02Z

src/channel.cr

+  # Closes the channel.
+  # The method prevents any new value from being sent to / received from the channel.
+  # It wakes up any sender / receiver fibers waiting on the channel.
+  # It only has effect *after* any previously enqueued value in the channel has been received, up to the channel's capacity.


I'd probably just say

All items successfully sent to the channel can be received before receive considers the channel closed, but send will consider the channel closed before close returns.

RX14 · 2019-10-29T20:49:44Z

src/channel.cr

+  # Closes the channel.
+  # The method prevents any new value from being sent to / received from the channel.
+  # It wakes up any sender / receiver fibers waiting on the channel.
+  # It only has effect *after* any previously enqueued value in the channel has been received, up to the channel's capacity.


I'd document and spec that. You can do that in this PR.

src/channel.cr

RX14

Just tiny nitpicks!

spec/std/channel_spec.cr

… than once

lbarasti mentioned this pull request Oct 20, 2019

Behaviour of unbuffered Channel#send on Channel#close in v0.31.x vs previous versions #8346

Closed

lbarasti commented Oct 20, 2019

View reviewed changes

RX14 reviewed Oct 29, 2019

View reviewed changes

RX14 requested changes Nov 5, 2019

View reviewed changes

spec/std/channel_spec.cr Outdated Show resolved Hide resolved

spec/std/channel_spec.cr Outdated Show resolved Hide resolved

lbarasti requested a review from RX14 November 6, 2019 18:59

lbarasti added 5 commits November 13, 2019 23:14

Add documentation for Channel#send and Channel#close (#8346)

917ae72

Clarify docs for #close

62c796b

Clarify docs for #send

fd53245

Document and test the behaviour of Channel when #close is called more…

287c8b8

… than once

Clarify docs for #close and make #close test more comprehensive

2150b52

RX14 approved these changes Nov 14, 2019

View reviewed changes

Merge branch 'master' into document-channel-send-and-close-behaviour

afe17aa

straight-shoota approved these changes Nov 25, 2019

View reviewed changes

straight-shoota added this to the 0.32.0 milestone Nov 25, 2019

straight-shoota added kind:docs topic:stdlib:concurrency labels Nov 25, 2019

straight-shoota merged commit 85baa80 into crystal-lang:master Nov 26, 2019

lbarasti deleted the document-channel-send-and-close-behaviour branch November 27, 2019 00:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for Channel#send and Channel#close (crystal-lang#8346) #8356

Add documentation for Channel#send and Channel#close (crystal-lang#8346) #8356

lbarasti commented Oct 20, 2019 •

edited by RX14

lbarasti Oct 20, 2019

lbarasti Oct 20, 2019

lbarasti Oct 20, 2019

RX14 Oct 29, 2019

lbarasti Oct 20, 2019 •

edited

RX14 Oct 29, 2019

lbarasti Oct 30, 2019

RX14 Oct 29, 2019

lbarasti Oct 29, 2019

RX14 Nov 5, 2019

lbarasti Nov 5, 2019

lbarasti Nov 5, 2019

RX14 Oct 29, 2019

RX14 Oct 29, 2019

RX14 left a comment

Add documentation for Channel#send and Channel#close (crystal-lang#8346) #8356

Add documentation for Channel#send and Channel#close (crystal-lang#8346) #8356

Conversation

lbarasti commented Oct 20, 2019 • edited by RX14

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lbarasti Oct 20, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RX14 left a comment

Choose a reason for hiding this comment

lbarasti commented Oct 20, 2019 •

edited by RX14

lbarasti Oct 20, 2019 •

edited