Proc::Async Reference

Running process (asynchronous interface)

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method new #

multi method new(*@ ($path, *@args), :$w, :$enc, :$translate-nl, :$arg0,
multi method new(   :$path, :@args,  :$w, :$enc, :$translate-nl, :$arg0,

Creates a new Proc::Async object with external program name or path $path and the command line arguments @args. If :w is passed to new, then a pipe to the external program's standard input stream (stdin) is opened, to which you can write with write and say. The :enc specifies the encoding for streams (can still be overridden in individual methods) and defaults

method stdout #

method stdout(Proc::Async:D: :$bin --> Supply:D)

Returns Supply:D.

Returns the Supply for the external program's standard output stream. If :bin is passed, the standard output is passed along in binary as Blob, otherwise it is interpreted as UTF-8, decoded, and passed along as Str. You must call stdout before you call .start. Otherwise an exception of class X::Proc::Async::TapBeforeSpawn is

method stderr #

method stderr(Proc::Async:D: :$bin --> Supply:D)

Returns Supply:D.

Returns the Supply for the external program's standard error stream. If :bin is passed, the standard error is passed along in binary as Blob, otherwise it is interpreted as UTF-8, decoded, and passed along as Str. You must call stderr before you call .start. Otherwise an exception of class X::Proc::Async::TapBeforeSpawn

method bind-stdin #

multi method bind-stdin(IO::Handle:D $handle)
multi method bind-stdin(Proc::Async::Pipe:D $pipe)

Sets a handle (which must be opened) or a Pipe as a source of STDIN. The STDIN of the target process must be writable or X::Proc::Async::BindOrUse will be thrown. This is equivalent to and will print the content of /etc/profile to standard output.

method bind-stdout #

method bind-stdout(IO::Handle:D $handle)

Redirects STDOUT of the target process to a handle (which must be opened). If STDOUT is closed X::Proc::Async::BindOrUse will be thrown. This program will pipe the output of the ls shell command to a file called ls.out, which we are opened for reading.

method bind-stderr #

method bind-stderr(IO::Handle:D $handle)

Redirects STDERR of the target process to a handle (which must be opened). If STDERR is closed X::Proc::Async::BindOrUse will be thrown.

method w #

method w(Proc::Async:D:)

Returns a true value if :w was passed to the constructor, that is, if the external program is started with its input stream made available to output to the program through the .print, .say and .write methods.

method start #

method start(Proc::Async:D: :$scheduler = $*SCHEDULER, :$ENV, :$cwd = $*CWD --> Promise)

Returns Promise.

Initiates spawning of the external program. Returns a Promise that will be kept with a Proc object once the external program exits or broken if the program cannot be started. Optionally, you can use a scheduler instead of the default $*SCHEDULER, or change the environment the process is going to run in via the named argument :$ENV or the directory via the named argument :$cwd.

method started #

method started(Proc::Async:D: --> Bool:D)

Returns Bool:D.

Returns False before .start has been called, and True afterwards.

method ready #

method ready(Proc::Async:D: --> Promise:D)

Returns Promise:D.

Returns a Promise that will be kept once the process has successfully started. Promise will be broken if the program fails to start. Implementation-specific note: Starting from Rakudo 2018.04, the returned promise will hold the process id (PID).

method pid #

method pid(Proc::Async:D: --> Promise:D)

Returns Promise:D.

Equivalent to ready. Returns a Promise that will be kept once the process has successfully started. Promise will be broken if the program fails to start. Returned promise will hold the process id (PID). Implementation-specific note: Available starting from Rakudo 2018.04.

method path #

method path(Proc::Async:D:)

Deprecated as of v6.d. Use command instead. Returns the name and/or path of the external program that was passed to the new method as first argument.

method args #

method args(Proc::Async:D: --> Positional:D)

Returns Positional:D.

Deprecated as of v6.d. Use command instead. Returns the command line arguments for the external programs, as passed to the new method.

method command #

method command(Proc::Async:D: --> List:D)

Returns List:D.

Available as of v6.d. Returns the command and arguments used for this Proc::Async object:

method write #

method write(Proc::Async:D: Blob:D $b, :$scheduler = $*SCHEDULER --> Promise:D)

Returns Promise:D.

Write the binary data in $b to the standard input stream of the external program. Returns a Promise that will be kept once the data has fully landed in the input buffer of the external program. The Proc::Async object must be created for writing (with Proc::Async.new(:w, $path, @args)). Otherwise an X::Proc::Async::OpenForWriting exception will the thrown.

method print #

method print(Proc::Async:D: Str() $str, :$scheduler = $*SCHEDULER)

Write the text data in $str to the standard input stream of the external program, encoding it as UTF-8. Returns a Promise that will be kept once the data has fully landed in the input buffer of the external program. The Proc::Async object must be created for writing (with Proc::Async.new(:w, $path, @args)). Otherwise an X::Proc::Async::OpenForWriting exception

method put #

method put(Proc::Async:D: \x, |c)

Does a .join on the output, adds a newline, and calls .print on it. Will throw if it's not started, or not open for writing.

method say #

method say(Proc::Async:D: $output, :$scheduler = $*SCHEDULER)

Calls method gist on the $output, adds a newline, encodes it as UTF-8, and sends it to the standard input stream of the external program, encoding it as UTF-8. Returns a Promise that will be kept once the data has fully landed in the input buffer of the external program. The Proc::Async object must be created for writing (with Proc::Async.new(:w, $path, @args)). Otherwise an

method pty #

method pty(--> Bool)

Returns Bool.

Returns whether the child process was created with a PTY.

method resize-pty #

method resize-pty(Int :$cols, Int :$rows)

Changes the size of the PTY the child is attached to.

method Supply #

multi method Supply(Proc::Async:D: :$bin!)
multi method Supply(Proc::Async:D: :$enc, :$translate-nl)

Returns a Supply of merged stdout and stderr streams. If :$bin named argument is provided, the Supply will be binary, producing Buf objects, otherwise, it will be in character mode, producing Str objects and :$enc named argument can specify encoding to use. The :$translate-nl option specifies whether new line endings should be

method close-stdin #

method close-stdin(Proc::Async:D: --> True)

Returns True.

Closes the standard input stream of the external program. Programs that read from STDIN often only terminate when their input stream is closed. So if waiting for the promise from .start hangs (for a program opened for writing), it might be a forgotten close-stdin. The Proc::Async object must be created for writing (with Proc::Async.new(:w, $path, @args)). Otherwise an

method kill #

multi method kill(Proc::Async:D: Signal:D \signal = SIGHUP)
multi method kill(Proc::Async:D: Int:D \signal)
multi method kill(Proc::Async:D: Str:D \signal)

Sends a signal to the running program. The signal can be a signal name ("KILL" or "SIGKILL"), an integer (9) or an element of the Signal enum (Signal::SIGKILL); by default and with no argument, the SIGHUP signal will be used.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

19 no-output · 2 rakupp-differs

class Proc::Async {}

my $file = ‘foo’.IO;
spurt $file, “and\nCamelia\n♡\nme\n”;

my $proc = Proc::Async.new: :w, ‘tac’, ‘--’, $file, ‘-’;
# my $proc = Proc::Async.new: :w, ‘sleep’, 15; # uncomment to try timeouts

react {
whenever $proc.stdout.lines { # split input on \r\n, \n, and \r
    say ‘line: ’, $_
}
whenever $proc.stderr { # chunks
    say ‘stderr: ’, $_
}
whenever $proc.ready {
    say ‘PID: ’, $_ # Only in Rakudo 2018.04 and newer, otherwise Nil
}
whenever $proc.start {
    say ‘Proc finished: exitcode=’, .exitcode, ‘ signal=’, .signal;
    done # gracefully jump from the react block
}
whenever $proc.print: “I\n♥\nCamelia\n” {
    $proc.close-stdin
}
whenever signal(SIGTERM).merge: signal(SIGINT) {
    once {
        say ‘Signal received, asking the process to stop’;
        $proc.kill; # sends SIGHUP, change appropriately
        whenever signal($_).zip: Promise.in(2).Supply {
            say ‘Kill it!’;
            $proc.kill: SIGKILL
        }
    }
}
whenever Promise.in(5) {
    say ‘Timeout. Asking the process to stop’;
    $proc.kill; # sends SIGHUP, change appropriately
    whenever Promise.in(2) {
        say ‘Timeout. Forcing the process to stop’;
        $proc.kill: SIGKILL
    }
}
}

say ‘Program finished’;

line: me
line: ♡
line: Camelia
line: and
line: Camelia
line: ♥
line: I
Proc finished: exitcode=0 signal=0
Program finished

# command with arguments
my $proc = Proc::Async.new('echo', 'foo', 'bar');

# subscribe to new output from out and err handles:
$proc.stdout.tap(-> $v { print "Output: $v" }, quit => { say 'caught exception ' ~ .^name });
$proc.stderr.tap(-> $v { print "Error:  $v" });

say "Starting...";
my $promise = $proc.start;

# wait for the external program to terminate
await $promise;
say "Done.";

Starting...
Output: foo bar
Done.

my $prog = Proc::Async.new(:w, 'hexdump', '-C');
my $promise = $prog.start;
await $prog.write(Buf.new(12, 42));
$prog.close-stdin;
await $promise;

my $proc-echo = Proc::Async.new: 'echo', 'Hello, world';
my $proc-cat = Proc::Async.new: 'cat', '-n';
$proc-cat.bind-stdin: $proc-echo.stdout;
await $proc-echo.start, $proc-cat.start;

                 :$win-verbatim-args = False, :$pty,
                 :$started = False --> Proc::Async:D)
                 :$win-verbatim-args = False, :$pty,
                 :$started = False --> Proc::Async:D)

my $proc = Proc::Async.new(:r, 'echo', 'Raku');
$proc.stdout.tap( -> $str {
    say "Got output '$str' from the external program";
});
my $promise = $proc.start;
await $promise;

my $proc = Proc::Async.new(:r, 'echo', 'Raku');
$proc.stderr.tap( -> $str {
    say "Got error '$str' from the external program";
});
my $promise = $proc.start;
await $promise;

my $p = Proc::Async.new("cat", :in);
my $h = "/etc/profile".IO.open;
$p.bind-stdin($h);
$p.start;

cat < /etc/profile

my $p = Proc::Async.new("ls", :out);
my $h = "ls.out".IO.open(:w);
$p.bind-stdout($h);
$p.start;

my $p = Proc::Async.new("ls", "--foo", :err);
my $h = "ls.err".IO.open(:w);
$p.bind-stderr($h);
$p.start;

try await $p.start;

try sink await $p.start;

my $p := Proc::Async.new: 'cat', 'some', 'files';
$p.command.say; # OUTPUT: «(cat some files)␤»

(cat some files)

(cat some files)

react {
with Proc::Async.new: «"$*EXECUTABLE" -e 'say 42; note 100'» {
    whenever .Supply { .print }  # OUTPUT: «42␤100␤»
    whenever .start {}
}
}

42
100

42
100