Start with supplies

Author: jonathanstowe

lib/Language/concurrency.pod

@@ -261,9 +261,57 @@ when the completion or otherwise of the tasks is more important to the
 consumer than the actual results, or the results have been collected by
 other means.
 
+
+=head2 Supplies
+
+A L<Supply> is an asynchronous data streaming mechanism that can be
+consumed by one or more consumers simultaneously in a manner similar to
+"events" in other programming languages and can be seem as enabling
+"Event Driven" or reactive designs.
+
+L<Supply> is a role that can be composed into your own types, but will 
+frequently be used as a "type punned" class to create standalone objects.
+
+At its simplest a L<Supply> is a message stream that can have multiple
+subscribers created with the method C<tap> on to which data items can be
+placed with C<emit> :
+
+    my $supply = Supply.new();
+
+    $supply.tap( -> $v { say $v });
+
+    for 1 .. 10 {
+        $supply.emit($_);
+    }
+
+The C<tap> method returns a L<Tap> object which can be used to obtain
+information about the tap and also to turn it off when we are no lomger
+interested in the events:
+
+    my $supply = Supply.new;
+    my $tap = $supply.tap(-> $v { say $v }, closing => {say "closing"});
+    $supply.emit("OK");
+    $tap.close; # Will trigger the closing callback
+    $supply.emit("Won't trigger the tap");
+
+Calling C<close> on the L<Tap> object (or calling C<close> on the supply
+object with the tap object as an argument,) will trigger the callback
+specified by C<closing> if present and stop further events being sent to
+the tap callback but otherwise leave the supply intact to receive further
+events. Calling C<done> on the supply object will similarly call the
+C<done> callback that may be specified for any taps but will not prevent any
+further events being emitted to the stream, or taps receiving them.
+
 =begin comment
 
-=head2 supplies
+I couldn't think of a non-contrived but succinct example for a use-case
+
+=end comment
+
+
+
+
+=begin comment
 
 =head3 tap