NAME
Venus::Process - Process Class
ABSTRACT
Process Class for Perl 5
SYNOPSIS
package main;
use Venus::Process;
my $parent = Venus::Process->new;
my $process = $parent->fork;
if ($process) {
# do something in child process ...
$process->exit;
}
else {
# do something in parent process ...
$parent->wait(-1);
}
# $parent->exit;
DESCRIPTION
This package provides methods for handling and forking processes.
ATTRIBUTES
This package has the following attributes:
alarm
alarm(Int $seconds) (Int)
The alarm attribute is used in calls to alarm when the process is forked, installing an alarm in the forked process if set.
Since 2.40
INHERITS
This package inherits behaviors from:
INTEGRATES
This package integrates behaviors from:
METHODS
This package provides the following methods:
chdir
chdir(Str $path) (Process)
The chdir method changes the working directory the current process is operating within.
Since 0.06
- chdir example 2
-
# given: synopsis; $parent = $parent->chdir('/tmp'); # bless({...}, 'Venus::Process')
- chdir example 3
-
# given: synopsis; $parent = $parent->chdir('/xyz'); # Exception! (isa Venus::Process::Error) (see error_on_chdir)
check
check(Int $pid) (Int, Int)
The check method does a non-blocking "waitpid" in perlfunc operation and returns the wait status. In list context, returns the specified process' exit code (if terminated).
Since 0.06
- check example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork; if ($process) { # in forked process ... $process->exit; } my $check = $parent->check($pid); # 0
- check example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork; if ($process) { # in forked process ... $process->exit; } my ($check, $status) = $parent->check('00000'); # (-1, -1)
- check example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork(sub{ $_->exit(1) }); if ($process) { # in forked process ... $process->exit; } my ($check, $status) = $parent->check($pid); # ($pid, 1)
count
count(Str | CodeRef $code, Any @args) (Int)
The count method dispatches to the method specified (or the "watchlist" if not specified) and returns a count of the items returned from the dispatched call.
Since 2.40
- count example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $count = $parent->count; # 0
- count example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($pid) = $parent->watch(1001); my $count = $parent->count; # 1
- count example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($pid) = $parent->watch(1001); my $count = $parent->count('watchlist'); # 1
daemon
daemon() (Process)
The daemon method detaches the process from controlling terminal and runs it in the background as system daemon. This method internally calls "disengage" and "setsid" and attempts to change the working directory to the root directory.
Since 0.06
- daemon example 1
-
# given: synopsis; my $daemon = $parent->daemon; # exits parent immediately # in forked process ... # $daemon->exit;
disengage
disengage() (Process)
The disengage method limits the interactivity of the process by changing the working directory to the root directory and redirecting its standard file descriptors from and to /dev/null
, or the OS' equivalent. These state changes can be undone by calling the "engage" method.
Since 0.06
- disengage example 1
-
# given: synopsis; $parent = $parent->disengage; # bless({...}, 'Venus::Process')
engage
engage() (Process)
The engage method ensures the interactivity of the process by changing the working directory to the directory used to launch the process, and by redirecting/returning its standard file descriptors from and to their defaults. This method effectively does the opposite of the "disengage" method.
Since 0.06
exit
exit(Int $status) (Int)
The exit method exits the program immediately.
Since 0.06
fork
fork(Str | CodeRef $code, Any @args) (Process, Int)
The fork method calls the system "fork" in perlfunc function and creates a new process running the same program at the same point (or call site). This method returns a new Venus::Process object representing the child process (from within the execution of the child process (or fork)), and returns undef
to the parent (or originating) process. In list context, this method returns both the process and PID (or process ID) of the child process. If a callback or argument is provided it will be executed in the child process.
Since 0.06
- fork example 1
-
# given: synopsis; $process = $parent->fork; # if ($process) { # # in forked process ... # $process->exit; # } # else { # # in parent process ... # $parent->wait(-1); # } # in child process # bless({...}, 'Venus::Process')
- fork example 2
-
# given: synopsis; my $pid; ($process, $pid) = $parent->fork; # if ($process) { # # in forked process ... # $process->exit; # } # else { # # in parent process ... # $parent->wait($pid); # } # in parent process # (undef, $pid)
- fork example 3
-
# given: synopsis; my $pid; ($process, $pid) = $parent->fork(sub{ $$_{started} = time; }); # if ($process) { # # in forked process ... # $process->exit; # } # else { # # in parent process ... # $parent->wait($pid); # } # in parent process # (undef, $pid)
- fork example 4
-
# given: synopsis; $process = $parent->fork(sub{}); # simulate fork failure # no forking attempted if NOT supported # Exception! (isa Venus::Process:Error) (see error_on_fork_support)
- fork example 5
-
# given: synopsis $process = $parent->do('alarm', 10)->fork; # if ($process) { # # in forked process with alarm installed ... # $process->exit; # } # else { # # in parent process ... # $parent->wait(-1); # } # in child process # bless({...}, 'Venus::Process')
forks
forks(Str | CodeRef $code, Any @args) (Process, ArrayRef[Int])
The forks method creates multiple forks by calling the "fork" method n
times, based on the count specified. As with the "fork" method, this method returns a new Venus::Process object representing the child process (from within the execution of the child process (or fork)), and returns undef
to the parent (or originating) process. In list context, this method returns both the process and an arrayref of PID values (or process IDs) for each of the child processes created. If a callback or argument is provided it will be executed in each child process.
Since 0.06
- forks example 1
-
# given: synopsis; $process = $parent->forks(5); # if ($process) { # # do something in (each) forked process ... # $process->exit; # } # else { # # do something in parent process ... # $parent->wait(-1); # } # bless({...}, 'Venus::Process')
- forks example 2
-
# given: synopsis; my $pids; ($process, $pids) = $parent->forks(5); # if ($process) { # # do something in (each) forked process ... # $process->exit; # } # else { # # do something in parent process ... # $parent->wait($_) for @$pids; # } # in parent process # (undef, $pids)
- forks example 3
-
# given: synopsis; my $pids; ($process, $pids) = $parent->forks(5, sub{ my ($fork, $pid, $iteration) = @_; # $iteration is the fork iteration index $fork->exit; }); # if ($process) { # # do something in (each) forked process ... # $process->exit; # } # else { # # do something in parent process ... # $parent->wait($_) for @$pids; # } # in child process # bless({...}, 'Venus::Process')
kill
kill(Str $signal, Int @pids) (Int)
The kill method calls the system "kill" in perlfunc function which sends a signal to a list of processes and returns truthy or falsy. Note: A truthy result doesn't necessarily mean all processes were successfully signalled.
Since 0.06
- kill example 1
-
# given: synopsis; if ($process = $parent->fork) { # in forked process ... $process->exit; } my $kill = $parent->kill('term', int $process); # 1
killall
killall(Str $name, Int @pids) (ArrayRef)
The killall method accepts a list of PIDs (or uses the "watchlist" if not provided) and returns the result of calling the "kill" method for each PID. Returns a list in list context.
Since 2.40
- killall example 1
-
# given: synopsis package main; if ($process = $parent->fork) { # in forked process ... $process->exit; } my $killall = $parent->killall('term'); # [1]
- killall example 2
-
# given: synopsis package main; if ($process = $parent->fork) { # in forked process ... $process->exit; } my $killall = $parent->killall('term', 1001..1004); # [1, 1, 1, 1]
pid
pid() (Int)
The pid method returns the PID of the current process.
Since 2.40
- pid example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $pid = $parent->pid; # 00000
pids
pids() (ArrayRef)
The pids method returns the PID of the current process, and the PIDs of any child processes.
Since 2.40
- pids example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $pids = $parent->pids; # [00000]
- pids example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001..1004); my $pids = $parent->pids; # [00000, 1001..1004]
ping
ping(Int @pids) (Int)
The ping method returns truthy if the process of the PID provided is active. If multiple PIDs are provided, this method will return the count of active PIDs.
Since 2.01
- ping example 1
-
# given: synopsis; if ($process = $parent->fork) { # in forked process ... $process->exit; } my $ping = $parent->ping(int $process); # 1
prune
prune() (Process)
The prune method removes all stopped processes and returns the invocant.
Since 2.40
- prune example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001); $parent = $parent->prune; # bless({...}, 'Venus::Process')
- prune example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $process = $parent->fork; if ($process) { # in forked process ... $process->exit; } $parent = $parent->prune; # bless({...}, 'Venus::Process')
- prune example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->work(sub { my ($process) = @_; # in forked process ... $process->exit; }); $parent = $parent->prune; # bless({...}, 'Venus::Process')
restart
restart(CodeRef $callback) (ArrayRef)
The restart method executes the callback provided for each PID returned by the "stopped" method, passing the pid and the results of "check" to the callback as arguments, and returns the result of each call as an arrayref. In list context, this method returns a list.
Since 2.40
- restart example 1
-
# given: synopsis package main; $parent->watch(1001); my $restart = $parent->restart(sub { my ($pid, $check, $exit) = @_; # redeploy stopped process return [$pid, $check, $exit]; }); # [[1001, 1001, 255]]
setsid
setsid() (Int)
The setsid method calls the "setsid" in POSIX function and sets the process group identifier of the current process.
Since 0.06
- setsid example 2
-
# given: synopsis; my $setsid = $parent->setsid; # Exception! (isa Venus::Process::Error) (see error_on_setid)
started
started() (ArrayRef)
The started method returns a list of PIDs whose processes have been started and which have not terminated. Returns a list in list context.
Since 2.40
- started example 1
-
# given: synopsis package main; my $started = $parent->started; # child not terminated # [...]
- started example 2
-
# given: synopsis package main; my $started = $parent->started; # child terminated # []
status
status(CodeRef $callback) (ArrayRef)
The status method executes the callback provided for each PID in the "watchlist", passing the pid and the results of "check" to the callback as arguments, and returns the result of each call as an arrayref. In list context, this method returns a list.
Since 2.40
- status example 1
-
# given: synopsis package main; $parent->watch(1001); my $status = $parent->status(sub { my ($pid, $check, $exit) = @_; # assuming process 1001 is still running (not terminated) return [$pid, $check, $exit]; }); # [[1001, 0, -1]]
- status example 2
-
# given: synopsis package main; $parent->watch(1001); my $status = $parent->status(sub { my ($pid, $check, $exit) = @_; # assuming process 1001 terminated with exit code 255 return [$pid, $check, $exit]; }); # [[1001, 1001, 255]]
- status example 3
-
# given: synopsis package main; $parent->watch(1001); my @status = $parent->status(sub { my ($pid, $check, $exit) = @_; # assuming process 1001 terminated with exit code 255 return [$pid, $check, $exit]; }); # ([1001, 1001, 255])
stderr
stderr(Str $path) (Process)
The stderr method redirects STDERR
to the path provided, typically /dev/null
or some equivalent. If called with no arguments STDERR
will be restored to its default.
Since 0.06
- stderr example 2
-
# given: synopsis; $parent = $parent->stderr('/nowhere'); # Exception! (isa Venus::Process:Error) (see error_on_stderr)
stdin
stdin(Str $path) (Process)
The stdin method redirects STDIN
to the path provided, typically /dev/null
or some equivalent. If called with no arguments STDIN
will be restored to its default.
Since 0.06
- stdin example 2
-
# given: synopsis; $parent = $parent->stdin('/nowhere'); # Exception! (isa Venus::Process::Error) (see error_on_stdin)
stdout
stdout(Str $path) (Process)
The stdout method redirects STDOUT
to the path provided, typically /dev/null
or some equivalent. If called with no arguments STDOUT
will be restored to its default.
Since 0.06
- stdout example 2
-
# given: synopsis; $parent = $parent->stdout('/nowhere'); # Exception! Venus::Process::Error (error_on_stdout)
stopped
stopped() (ArrayRef)
The stopped method returns a list of PIDs whose processes have terminated. Returns a list in list context.
Since 2.40
- stopped example 1
-
# given: synopsis package main; my $stopped = $parent->stopped; # child terminated # [...]
- stopped example 2
-
# given: synopsis package main; my $stopped = $parent->stopped; # child not terminated # []
trap
trap(Str $name, Str | CodeRef $expr) (Process)
The trap method registers a process signal trap (or callback) which will be invoked whenever the current process receives that matching signal. The signal traps are globally installed and will overwrite any preexisting behavior. Signal traps are inherited by child processes (or forks) but can be overwritten using this method, or reverted to the default behavior by using the "untrap" method.
Since 0.06
- trap example 1
-
# given: synopsis; $parent = $parent->trap(term => sub{ die 'Something failed!'; }); # bless({...}, 'Venus::Process')
untrap
untrap(Str $name) (Process)
The untrap method restores the process signal trap specified to its default behavior. If called with no arguments, it restores all signal traps overwriting any user-defined signal traps in the current process.
Since 0.06
- untrap example 1
-
# given: synopsis; $parent->trap(chld => 'ignore')->trap(term => sub{ die 'Something failed!'; }); $parent = $parent->untrap('term'); # bless({...}, 'Venus::Process')
- untrap example 2
-
# given: synopsis; $parent->trap(chld => 'ignore')->trap(term => sub{ die 'Something failed!'; }); $parent = $parent->untrap; # bless({...}, 'Venus::Process')
unwatch
unwatch(Int @pids) (ArrayRef)
The unwatch method removes the PIDs provided from the watchlist and returns the list of PIDs remaining to be watched. In list context returns a list.
Since 2.40
- unwatch example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $unwatch = $parent->unwatch; # []
- unwatch example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001..1004); my $unwatch = $parent->unwatch(1001); # [1002..1004]
- unwatch example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001..1004); my $unwatch = $parent->unwatch(1002, 1004); # [1001, 1003]
wait
wait(Int $pid) (Int, Int)
The wait method does a blocking "waitpid" in perlfunc operation and returns the wait status. In list context, returns the specified process' exit code (if terminated).
Since 0.06
- wait example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork; if ($process) { # in forked process ... $process->exit; } my $wait = $parent->wait($pid); # 0
- wait example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork; if ($process) { # in forked process ... $process->exit; } my ($wait, $status) = $parent->wait('00000'); # (-1, -1)
- wait example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork(sub{ $_->exit(1) }); if ($process) { # in forked process ... $process->exit; } my ($wait, $status) = $parent->wait($pid); # ($pid, 1)
waitall
waitall(Int @pids) (ArrayRef)
The waitall method does a blocking "wait" call for all processes based on the PIDs provided (or the PIDs returned by "watchlist" if not provided) and returns an arrayref of results from calling "wait" on each PID. Returns a list in list context.
Since 2.40
- waitall example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $waitall = $parent->waitall; # []
- waitall example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $waitall = $parent->waitall(1001); # [[1001, 0]]
- waitall example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; my ($process, $pid) = $parent->fork; if ($process) { # in forked process ... $process->exit; } my $waitall = $parent->waitall; # [[$pid, 0]]
watch
watch(Int @pids) (ArrayRef)
The watch method records PIDs to be watched, e.g. using the "status" method and returns all PIDs being watched. Returns a list in list context.
Since 2.40
- watch example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $watch = $parent->watch; # []
- watch example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $watch = $parent->watch(1001..1004); # [1001..1004]
- watch example 3
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $watch = $parent->watch(1001..1004, 1001..1004); # [1001..1004]
- watch example 4
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001..1004); my $watch = $parent->watch; # [1001..1004]
- watch example 5
-
package main; use Venus::Process; my $parent = Venus::Process->new; my @watch = $parent->watch(1001..1004); # (1001..1004)
watchlist
watchlist() (ArrayRef)
The watchlist method returns the recorded PIDs. Returns a list in list context.
Since 2.40
- watchlist example 1
-
package main; use Venus::Process; my $parent = Venus::Process->new; my $watchlist = $parent->watchlist; # []
- watchlist example 2
-
package main; use Venus::Process; my $parent = Venus::Process->new; $parent->watch(1001..1004); my $watchlist = $parent->watchlist; # [1001..1004]
work
work(Str | CodeRef $code, Any @args) (Int)
The work method forks the current process, runs the callback provided in the child process, and immediately exits after. This method returns the PID of the child process. It is recommended to install an "alarm" in perlfunc in the child process (i.e. callback) to avoid creating zombie processes in situations where the parent process might exit before the child process is done working.
Since 0.06
- work example 1
-
# given: synopsis; my $pid = $parent->work(sub{ my ($process) = @_; # in forked process ... $process->exit; }); # $pid
works
works(Int $count, CodeRef $callback, Any @args) (ArrayRef)
The works method creates multiple forks by calling the "work" method n
times, based on the count specified. The works method runs the callback provided in the child process, and immediately exits after with an exit code of 0
by default. This method returns the PIDs of the child processes. It is recommended to install an "alarm" in perlfunc in the child process (i.e. callback) to avoid creating zombie processes in situations where the parent process might exit before the child process is done working.
Since 2.40
- works example 1
-
# given: synopsis; my $pids = $parent->works(5, sub{ my ($process) = @_; # in forked process ... $process->exit; }); # $pids
ERRORS
This package may raise the following errors:
- error:
error_on_chdir
-
This package may raise an error_on_chdir exception.
example 1
# given: synopsis; my @args = ('/nowhere', 123); my $error = $parent->throw('error_on_chdir', @args)->catch('error'); # my $name = $error->name; # "on_chdir" # my $message = $error->message; # "Can't chdir \"$path\": $!" # my $path = $error->stash('path'); # "/nowhere" # my $pid = $error->stash('pid'); # 123
- error:
error_on_fork_process
-
This package may raise an error_on_fork_process exception.
example 1
# given: synopsis; my @args = (123); my $error = $parent->throw('error_on_fork_process', @args)->catch('error'); # my $name = $error->name; # "on_fork_process" # my $message = $error->message; # "Can't fork process $pid: $!" # my $pid = $error->stash('pid'); # "123"
- error:
error_on_fork_support
-
This package may raise an error_on_fork_support exception.
example 1
# given: synopsis; my @args = (123); my $error = $parent->throw('error_on_fork_support', @args)->catch('error'); # my $name = $error->name; # "on_fork_support" # my $message = $error->message; # "Can't fork process $pid: Fork emulation not supported" # my $pid = $error->stash('pid'); # 123
- error:
error_on_setid
-
This package may raise an error_on_setid exception.
example 1
# given: synopsis; my @args = (123); my $error = $parent->throw('error_on_setid', @args)->catch('error'); # my $name = $error->name; # "on_setid" # my $message = $error->message; # "Can't start a new session: $!" # my $pid = $error->stash('pid'); # 123
- error:
error_on_stderr
-
This package may raise an error_on_stderr exception.
example 1
# given: synopsis; my @args = ("/nowhere", 123); my $error = $parent->throw('error_on_stderr', @args)->catch('error'); # my $name = $error->name; # "on_stderr" # my $message = $error->message; # "Can't redirect STDERR to \"/nowhere\": $!" # my $path = $error->stash('path'); # "/nowhere" # my $pid = $error->stash('pid'); # 123
- error:
error_on_stdin
-
This package may raise an error_on_stdin exception.
example 1
# given: synopsis; my @args = ('/nowhere', 123); my $error = $parent->throw('error_on_stdin', @args)->catch('error'); # my $name = $error->name; # "on_stdin" # my $message = $error->message; # "Can't redirect STDIN to \"$path\": $!" # my $path = $error->stash('path'); # "/nowhere" # my $pid = $error->stash('pid'); # 123
- error:
error_on_stdout
-
This package may raise an error_on_stdout exception.
example 1
# given: synopsis; my @args = ( '/nowhere', 123); my $error = $parent->throw('error_on_stdout', @args)->catch('error'); # my $name = $error->name; # "on_stdout" # my $message = $error->message; # "Can't redirect STDOUT to \"$path\": $!" # my $path = $error->stash('path'); # "/nowhere" # my $pid = $error->stash('pid'); # 123
OPERATORS
This package overloads the following operators:
- operation:
("")
-
This package overloads the
""
operator.example 1
# given: synopsis; my $result = "$parent"; # $pid
- operation:
(~~)
-
This package overloads the
~~
operator.example 1
# given: synopsis; my $result = $parent ~~ /^\d+$/; # 1
AUTHORS
Awncorp, awncorp@cpan.org
LICENSE
Copyright (C) 2000, Al Newkirk.
This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.