document class Channel

Author: moritz

lib/Type/Channel.pod

@@ -0,0 +1,89 @@
+=begin pod
+
+=TITLE class Channel
+
+=SUBTITLE A thread-safe way to send a series of values from producers to consumers
+
+    class Channel { ... }
+
+A Channel is a thread-safe queue that helps you to a series of objects from
+potentially mutltiple produces to potentially multiple consumers.
+
+    my $c = Channel.new;
+    await (^10).map: {
+        start {
+            my $r = rand;
+            sleep $r;
+            $c.send($r);
+        }
+    }
+    $c.close;
+    say $c.list;
+
+=head1 Methods
+
+=head2 method send
+
+    method send(Channel:D: \item)
+
+Enqueues an into the channel. Throws an exception of type
+C<X::Channel::SendOnClosed> if the channel has been closed already.
+
+=head2 method receive
+
+    method receive(Channel:D:)
+
+Receives and removes an item from the channel. It blocks if no item is
+present, waiting for a C<.send> from another thread.
+
+Throws an exception of
+type C<X::Channel::ReceiveOnClose> if the channel has been closed, and the
+last item has been removed already.
+
+If the channel has been marked as erratic with method C<fail>, and the last
+item has been removed, throws the argument that was given to C<fail> as an
+exception.
+
+See method C<poll> for a non-blocking version that won't throw exceptions.
+
+=head2 method poll
+
+    method poll(Channel:D:)
+
+Receives and removes an item from the channel. If no item is present, returns
+C<Nil> instead of waiting.
+
+See method C<receive> for a blocking version that properly responds to channel
+closing and failure.
+
+=head2 method close
+
+    method close(Channel:D:)
+
+Close the channel. This makes subsequent C<send> calls die, as well as a
+C<receive> call past the end of the queue,
+and is a prerequisite for C<list> to terminate.
+
+=head2 method list
+
+    method list(Channel:D:) returns List:D
+
+Returns a list of all remaining items in the queue, and removes them from the
+channel. This can only terminate once C<.close> has been called.
+
+=head2 method closed
+
+    method closed(Channel:D:) returns Promise:D
+
+Returns a promise that will be kept once the channel is closed by a call to
+method C<close>.
+
+=head2 method fail
+
+    method fail(Channel:D: $error)
+
+Closes the channel (that is, makes subsequent C<send> calls die), and enqueues
+the error as the final element in the channel. Method C<receive> will throw
+the error as an exception.
+
+=end pod