Proc::Async basics

Author: jonathanstowe

lib/Language/concurrency.pod

@@ -447,6 +447,68 @@ each time it is called.  This could be used, for instance, to fan-out a
 L<Supply> to one or more L<Channel>s to provide for different interfaces
 in a program.
 
+=head2 Proc::Async
+
+L<Proc::Async> builds on the facilities described to run and interact with
+an external program asynchronously:
+
+    my $proc = Proc::Async.new('echo', 'foo', 'bar');
+
+    $proc.stdout.tap(-> $v { print "Output: $v" });
+    $proc.stderr.tap(-> $v { print "Error:  $v" });
+
+    say "Starting...";
+    my $promise = $proc.start;
+
+    await $promise;
+    say "Done.";
+
+    # Output:
+    # Starting...
+    # Output: foo bar
+    # Done.
+
+The path to the command and any arguments are supplied to
+the constructor but the program will not be started until
+L<start|/type/Proc::Async#method_start> is called, which will return
+a L<Promise> that will be kept when the program exits. The standard
+output and standard error of the program are available as L<Supply>
+objects from the methods L<stdout|/type/Proc::Async#method_stdout>
+and L<stderr|/type/Proc::Async#method_stderr> respectively which can be
+tapped as required.
+
+If you want to write to the standard input of the program
+you can supply the C<:w> adverb to the constructor and use
+the methods L<write|/type/Proc::Async#method_write>,
+L<print|/type/Proc::Async#method_print> or
+L<say|/type/Proc::Async#method_say> to write to the opened pipe once
+the program has been started:
+
+    my $proc = Proc::Async.new(:w, 'grep', 'foo');
+
+    $proc.stdout.tap(-> $v { print "Output: $v" });
+
+    say "Starting...";
+    my $promise = $proc.start;
+
+    $proc.say("this line has foo");
+    $proc.say("this one doesn't");
+
+    $proc.close-stdin;
+    await $promise;
+    say "Done.";
+
+    # Output:
+    # Starting...
+    # Output: this line has foo
+    # Done.
+
+Some programs (such as C<grep> without a file argument in this
+example, ) won't exit until their standard input is closed so
+L<close-stdin|/type/Proc::Async#method_close-stdin> can be called when
+you are finished writing to allow the L<Promise> returned by C<start>
+to be kept.
+
 =head1 Low-level APIs
 
 =head2 Threads