Module: Process
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Defined in: | process.c, process.c, ruby.c |
Overview
Module Process
represents a process in the underlying operating system. Its methods support management of the current process and its child processes.
Process Creation
Each of the following methods executes a given command in a new process or subshell, or multiple commands in new processes and/or subshells. The choice of process or subshell depends on the form of the command; see Argument command_line or exe_path
.
-
.spawn, Kernel.spawn: Executes the command; returns the new pid without waiting for completion.
-
.exec: Replaces the current process by executing the command.
In addition:
-
Method Kernel.system executes a given command-line (string) in a subshell; returns
true
,false
, ornil
. -
Method
Kernel.‘
executes a given command-line (string) in a subshell; returns its $stdout string. -
Module Open3 supports creating child processes with access to their $stdin, $stdout, and $stderr streams.
Execution Environment
Optional leading argument env
is a hash of name/value pairs, where each name is a string and each value is a string or nil
; each name/value pair is added to ::ENV
in the new process.
Process.spawn( 'ruby -e "p ENV[\"Foo\"]"')
Process.spawn({'Foo' => '0'}, 'ruby -e "p ENV[\"Foo\"]"')
Output:
"0"
The effect is usually similar to that of calling ENV#update
with argument env
, where each named environment variable is created or updated (if the value is non-nil
), or deleted (if the value is nil
).
However, some modifications to the calling process may remain if the new process fails. For example, hard resource limits are not restored.
Argument command_line
or exe_path
The required string argument is one of the following:
-
command_line
if it begins with a shell reserved word or special built-in, or if it contains one or more meta characters. -
exe_path
otherwise.
Argument command_line
String argument command_line
is a command line to be passed to a shell; it must begin with a shell reserved word, begin with a special built-in, or contain meta characters:
system('if true; then echo "Foo"; fi') # => true # Shell reserved word.
system('exit') # => true # Built-in.
system('date > /tmp/date.tmp') # => true # Contains meta character.
system('date > /nop/date.tmp') # => false
system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.
The command line may also contain arguments and options for the command:
system('echo "Foo"') # => true
Output:
Foo
See Execution Shell
for details about the shell.
Argument exe_path
Argument exe_path
is one of the following:
-
The string path to an executable file to be called:
Example:
system('/usr/bin/date') # => true # Path to date on Unix-style system. system('foo') # => nil # Command execlution failed.
Output:
Thu Aug 31 10:06:48 AM CDT 2023
A path or command name containing spaces without arguments cannot be distinguished from
command_line
above, so you must quote or escape the entire command name using a shell in platform dependent manner, or use the array form below.If
exe_path
does not contain any path separator, an executable file is searched from directories specified with thePATH
environment variable. What the word “executable” means here is depending on platforms.Even if the file considered “executable”, its content may not be in proper executable format. In that case, Ruby tries to run it by using
/bin/sh
on a Unix-like system, like system(3) does.File.write('shell_command', 'echo $SHELL', perm: 0o755) system('./shell_command') # prints "/bin/sh" or something.
-
A 2-element array containing the path to an executable and the string to be used as the name of the executing process:
Example:
pid = spawn(['sleep', 'Hello!'], '1') # 2-element array. p `ps -p #{pid} -o command=`
Output:
"Hello! 1\n"
Arguments args
If command_line
does not contain shell meta characters except for spaces and tabs, or exe_path
is given, Ruby invokes the executable directly. This form does not use the shell:
spawn("doesnt_exist") # Raises Errno::ENOENT
spawn("doesnt_exist", "\n") # Raises Errno::ENOENT
spawn("doesnt_exist\n") # => false
# sh: 1: doesnot_exist: not found
The error message is from a shell and would vary depending on your system.
If one or more args
is given after exe_path
, each is an argument or option to be passed to the executable:
Example:
system('echo', '<', 'C*', '|', '$SHELL', '>') # => true
Output:
< C* | $SHELL >
However, there are exceptions on Windows. See Execution Shell on Windows.
If you want to invoke a path containing spaces with no arguments without shell, you will need to use a 2-element array exe_path
.
Example:
path = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
spawn(path) # Raises Errno::ENOENT; No such file or directory - /Applications/Google
spawn([path] * 2)
Execution Options
Optional trailing argument options
is a hash of execution options.
Working Directory (:chdir
)
By default, the working directory for the new process is the same as that of the current process:
Dir.chdir('/var')
Process.spawn('ruby -e "puts Dir.pwd"')
Output:
/var
Use option :chdir
to set the working directory for the new process:
Process.spawn('ruby -e "puts Dir.pwd"', {chdir: '/tmp'})
Output:
/tmp
The working directory of the current process is not changed:
Dir.pwd # => "/var"
File Redirection (File Descriptor)
Use execution options for file redirection in the new process.
The key for such an option may be an integer file descriptor (fd), specifying a source, or an array of fds, specifying multiple sources.
An integer source fd may be specified as:
-
n: Specifies file descriptor n.
There are these shorthand symbols for fds:
-
:in
: Specifies file descriptor 0 (STDIN). -
:out
: Specifies file descriptor 1 (STDOUT). -
:err
: Specifies file descriptor 2 (STDERR).
The value given with a source is one of:
-
n: Redirects to fd n in the parent process.
-
filepath
: Redirects from or to the file atfilepath
viaopen(filepath, mode, 0644)
, wheremode
is'r'
for source:in
, or'w'
for source:out
or:err
. -
[filepath]
: Redirects from the file atfilepath
viaopen(filepath, 'r', 0644)
. -
[filepath, mode]
: Redirects from or to the file atfilepath
viaopen(filepath, mode, 0644)
. -
[filepath, mode, perm]
: Redirects from or to the file atfilepath
viaopen(filepath, mode, perm)
. -
[:child, fd]
: Redirects to the redirectedfd
. -
:close
: Closes the file descriptor in child process.
See Access Modes
and {File
Permissions}.
Environment Variables (:unsetenv_others
)
By default, the new process inherits environment variables from the parent process; use execution option key :unsetenv_others
with value true
to clear environment variables in the new process.
Any changes specified by execution option env
are made after the new process inherits or clears its environment variables; see Execution Environment
.
File-Creation Access (:umask
)
Use execution option :umask
to set the file-creation access for the new process; see Access Modes
:
command = 'ruby -e "puts sprintf(\"0%o\", File.umask)"'
= {:umask => 0644}
Process.spawn(command, )
Output:
0644
Process Groups (:pgroup
and :new_pgroup
)
By default, the new process belongs to the same process group as the parent process.
To specify a different process group. use execution option :pgroup
with one of the following values:
-
true
: Create a new process group for the new process. -
pgid: Create the new process in the process group whose id is pgid.
On Windows only, use execution option :new_pgroup
with value true
to create a new process group for the new process.
Resource Limits
Use execution options to set resource limits.
The keys for these options are symbols of the form :rlimit_resource_name
, where resource_name is the downcased form of one of the string resource names described at method .setrlimit. For example, key :rlimit_cpu
corresponds to resource limit 'CPU'
.
The value for such as key is one of:
-
An integer, specifying both the current and maximum limits.
-
A 2-element array of integers, specifying the current and maximum limits.
File Descriptor Inheritance
By default, the new process inherits file descriptors from the parent process.
Use execution option :close_others => true
to modify that inheritance by closing non-standard fds (3 and greater) that are not otherwise redirected.
Execution Shell
On a Unix-like system, the shell invoked is /bin/sh
; the entire string command_line
is passed as an argument to shell option -c.
The shell performs normal shell expansion on the command line:
Example:
system('echo $SHELL: C*') # => true
Output:
/bin/bash: CONTRIBUTING.md COPYING COPYING.ja
Execution Shell on Windows
On Windows, the shell invoked is determined by environment variable RUBYSHELL
, if defined, or COMSPEC
otherwise; the entire string command_line
is passed as an argument to -c
option for RUBYSHELL
, as well as /bin/sh
, and /c option for COMSPEC
. The shell is invoked automatically in the following cases:
-
The command is a built-in of
cmd.exe
, such asecho
. -
The executable file is a batch file; its name ends with
.bat
or.cmd
.
Note that the command will still be invoked as command_line
form even when called in exe_path
form, because cmd.exe
does not accept a script name like /bin/sh
does but only works with /c
option.
The standard shell cmd.exe
performs environment variable expansion but does not have globbing functionality:
Example:
system("echo %COMSPEC%: C*")' # => true
Output:
C:\WINDOWS\system32\cmd.exe: C*
What’s Here
Current-Process Getters
-
.argv0: Returns the process name as a frozen string.
-
.egid: Returns the effective group ID.
-
.euid: Returns the effective user ID.
-
.getpgrp: Return the process group ID.
-
.getrlimit: Returns the resource limit.
-
.gid: Returns the (real) group ID.
-
.pid: Returns the process ID.
-
.ppid: Returns the process ID of the parent process.
-
.uid: Returns the (real) user ID.
Current-Process Setters
-
.egid=: Sets the effective group ID.
-
.euid=: Sets the effective user ID.
-
.gid=: Sets the (real) group ID.
-
.setproctitle: Sets the process title.
-
.setpgrp: Sets the process group ID of the process to zero.
-
.setrlimit: Sets a resource limit.
-
.setsid: Establishes the process as a new session and process group leader, with no controlling tty.
-
.uid=: Sets the user ID.
Current-Process Execution
-
.abort: Immediately terminates the process.
-
.daemon: Detaches the process from its controlling terminal and continues running it in the background as system daemon.
-
.exec: Replaces the process by running a given external command.
-
.exit: Initiates process termination by raising exception
::SystemExit
(which may be caught). -
.exit!: Immediately exits the process.
-
.warmup: Notifies the Ruby virtual machine that the boot sequence for the application is completed, and that the VM may begin optimizing the application.
Child Processes
-
.detach: Guards against a child process becoming a zombie.
-
.fork: Creates a child process.
-
.kill: Sends a given signal to processes.
-
.spawn: Creates a child process.
-
.wait, .waitpid: Waits for a child process to exit; returns its process ID.
-
.wait2, .waitpid2: Waits for a child process to exit; returns its process ID and status.
-
.waitall: Waits for all child processes to exit; returns their process IDs and statuses.
Process Groups
-
.getpgid: Returns the process group ID for a process.
-
.getpriority: Returns the scheduling priority for a process, process group, or user.
-
.getsid: Returns the session ID for a process.
-
.groups: Returns an array of the group IDs in the supplemental group access list for this process.
-
.groups=: Sets the supplemental group access list to the given array of group IDs.
-
.initgroups: Initializes the supplemental group access list.
-
.last_status: Returns the status of the last executed child process in the current thread.
-
.maxgroups: Returns the maximum number of group IDs allowed in the supplemental group access list.
-
.maxgroups=: Sets the maximum number of group IDs allowed in the supplemental group access list.
-
.setpgid: Sets the process group ID of a process.
-
.setpriority: Sets the scheduling priority for a process, process group, or user.
Timing
-
.clock_getres: Returns the resolution of a system clock.
-
.clock_gettime: Returns the time from a system clock.
-
.times: Returns a
Tms
object containing times for the current process and its child processes.
Constant Summary
-
CLOCK_BOOTTIME =
see .clock_gettime
CLOCKID2NUM(CLOCK_BOOTTIME)
-
CLOCK_BOOTTIME_ALARM =
see .clock_gettime
CLOCKID2NUM(CLOCK_BOOTTIME_ALARM)
-
CLOCK_MONOTONIC =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC)
-
CLOCK_MONOTONIC_COARSE =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC_COARSE)
-
CLOCK_MONOTONIC_FAST =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC_FAST)
-
CLOCK_MONOTONIC_PRECISE =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC_PRECISE)
-
CLOCK_MONOTONIC_RAW =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC_RAW)
-
CLOCK_MONOTONIC_RAW_APPROX =
see .clock_gettime
CLOCKID2NUM(CLOCK_MONOTONIC_RAW_APPROX)
-
CLOCK_PROCESS_CPUTIME_ID =
see .clock_gettime
CLOCKID2NUM(CLOCK_PROCESS_CPUTIME_ID)
-
CLOCK_PROF =
see .clock_gettime
CLOCKID2NUM(CLOCK_PROF)
-
CLOCK_REALTIME =
see .clock_gettime
CLOCKID2NUM(CLOCK_REALTIME)
-
CLOCK_REALTIME_ALARM =
see .clock_gettime
CLOCKID2NUM(CLOCK_REALTIME_ALARM)
-
CLOCK_REALTIME_COARSE =
see .clock_gettime
CLOCKID2NUM(CLOCK_REALTIME_COARSE)
-
CLOCK_REALTIME_FAST =
see .clock_gettime
CLOCKID2NUM(CLOCK_REALTIME_FAST)
-
CLOCK_REALTIME_PRECISE =
see .clock_gettime
CLOCKID2NUM(CLOCK_REALTIME_PRECISE)
-
CLOCK_SECOND =
see .clock_gettime
CLOCKID2NUM(CLOCK_SECOND)
-
CLOCK_TAI =
see .clock_gettime
CLOCKID2NUM(CLOCK_TAI)
-
CLOCK_THREAD_CPUTIME_ID =
see .clock_gettime
CLOCKID2NUM(CLOCK_THREAD_CPUTIME_ID)
-
CLOCK_UPTIME =
see .clock_gettime
CLOCKID2NUM(CLOCK_UPTIME)
-
CLOCK_UPTIME_FAST =
see .clock_gettime
CLOCKID2NUM(CLOCK_UPTIME_FAST)
-
CLOCK_UPTIME_PRECISE =
see .clock_gettime
CLOCKID2NUM(CLOCK_UPTIME_PRECISE)
-
CLOCK_UPTIME_RAW =
see .clock_gettime
CLOCKID2NUM(CLOCK_UPTIME_RAW)
-
CLOCK_UPTIME_RAW_APPROX =
see .clock_gettime
CLOCKID2NUM(CLOCK_UPTIME_RAW_APPROX)
-
CLOCK_VIRTUAL =
see .clock_gettime
CLOCKID2NUM(CLOCK_VIRTUAL)
-
PRIO_PGRP =
see .setpriority
INT2FIX(PRIO_PGRP)
-
PRIO_PROCESS =
see .setpriority
INT2FIX(PRIO_PROCESS)
-
PRIO_USER =
see .setpriority
INT2FIX(PRIO_USER)
-
RLIMIT_AS =
Maximum size of the process’s virtual memory (address space) in bytes.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_AS)
-
RLIMIT_CORE =
Maximum size of the core file.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_CORE)
-
RLIMIT_CPU =
CPU time limit in seconds.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_CPU)
-
RLIMIT_DATA =
Maximum size of the process’s data segment.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_DATA)
-
RLIMIT_FSIZE =
Maximum size of files that the process may create.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_FSIZE)
-
RLIMIT_MEMLOCK =
Maximum number of bytes of memory that may be locked into RAM.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_MEMLOCK)
-
RLIMIT_MSGQUEUE =
Specifies the limit on the number of bytes that can be allocated for POSIX message queues for the real user ID of the calling process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_MSGQUEUE)
-
RLIMIT_NICE =
Specifies a ceiling to which the process’s nice value can be raised.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_NICE)
-
RLIMIT_NOFILE =
Specifies a value one greater than the maximum file descriptor number that can be opened by this process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_NOFILE)
-
RLIMIT_NPROC =
The maximum number of processes that can be created for the real user ID of the calling process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_NPROC)
-
RLIMIT_NPTS =
The maximum number of pseudo-terminals that can be created for the real user ID of the calling process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_NPTS)
-
RLIMIT_RSS =
Specifies the limit (in pages) of the process’s resident set.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_RSS)
-
RLIMIT_RTPRIO =
Specifies a ceiling on the real-time priority that may be set for this process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_RTPRIO)
-
RLIMIT_RTTIME =
Specifies limit on CPU time this process scheduled under a real-time scheduling policy can consume.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_RTTIME)
-
RLIMIT_SBSIZE =
Maximum size of the socket buffer.
INT2FIX(RLIMIT_SBSIZE)
-
RLIMIT_SIGPENDING =
Specifies a limit on the number of signals that may be queued for the real user ID of the calling process.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_SIGPENDING)
-
RLIMIT_STACK =
Maximum size of the stack, in bytes.
see the system getrlimit(2) manual for details.
INT2FIX(RLIMIT_STACK)
-
RLIM_INFINITY =
see .setrlimit
inf
-
RLIM_SAVED_CUR =
see .setrlimit
v
-
RLIM_SAVED_MAX =
see .setrlimit
v
-
WNOHANG =
see .wait
INT2FIX(WNOHANG)
-
WUNTRACED =
see .wait
INT2FIX(WUNTRACED)
Class Attribute Summary
-
.euid ⇒ Integer
rw
mod_func
Returns the effective user ID for the current process.
-
.euid=(new_euid) ⇒ new_euid
rw
mod_func
Sets the effective user ID for the current process.
-
.gid ⇒ Integer
rw
mod_func
Returns the (real) group ID for the current process:
-
.gid=(new_gid) ⇒ new_gid
rw
mod_func
Sets the group ID for the current process to
new_gid
: -
.groups ⇒ Array
rw
mod_func
Returns an array of the group IDs in the supplemental group access list for the current process:
-
.groups=(new_groups) ⇒ new_groups
rw
mod_func
Sets the supplemental group access list to the given array of group IDs.
-
.maxgroups ⇒ Integer
rw
mod_func
Returns the maximum number of group IDs allowed in the supplemental group access list:
-
.maxgroups=(new_max) ⇒ new_max
rw
mod_func
Sets the maximum number of group IDs allowed in the supplemental group access list.
-
.uid ⇒ Integer
rw
mod_func
Returns the (real) user ID of the current process.
-
.uid=(new_uid) ⇒ new_uid
rw
mod_func
Sets the (user) user ID for the current process to
new_uid
:
Class Method Summary
-
._fork ⇒ Integer
An internal API for fork.
-
.abort
Alias for Kernel.abort.
-
.exec([env, ] command_line, options = {})
Alias for Kernel.exec.
-
.exit(status = true)
Alias for Kernel.exit.
-
.exit!(status = false)
Alias for Kernel.exit!.
-
.fork
Alias for Kernel.fork.
-
.last_status ⇒ Process?
Returns a
Status
object representing the most recently exited child process in the current thread, ornil
if none: -
.spawn([env, ] command_line, options = {}) ⇒ pid
Alias for Kernel.spawn.
-
.argv0 ⇒ frozen_string
mod_func
Returns the name of the script being executed.
-
.clock_getres(clock_id, unit = :float_second) ⇒ Numeric
mod_func
Returns a clock resolution as determined by POSIX function clock_getres():
-
.clock_gettime(clock_id, unit = :float_second) ⇒ Numeric
mod_func
Returns a clock time as determined by POSIX function clock_gettime():
-
.daemon(nochdir = nil, noclose = nil) ⇒ 0
mod_func
Detaches the current process from its controlling terminal and runs it in the background as system daemon; returns zero.
-
.detach(pid) ⇒ Thread
mod_func
Avoids the potential for a child process to become a zombie process.
-
.egid ⇒ Integer
mod_func
Returns the effective group ID for the current process:
-
.egid=(new_egid) ⇒ new_egid
mod_func
Sets the effective group ID for the current process.
-
.getpgid(pid) ⇒ Integer
mod_func
Returns the process group ID for the given process ID .pid:
-
.getpgrp ⇒ Integer
mod_func
Returns the process group ID for the current process:
-
.getpriority(kind, id) ⇒ Integer
mod_func
Returns the scheduling priority for specified process, process group, or user.
-
.getrlimit(resource) ⇒ Array, max_limit
mod_func
Returns a 2-element array of the current (soft) limit and maximum (hard) limit for the given
resource
. -
.getsid(pid = nil) ⇒ Integer
mod_func
Returns the session ID of the given process ID .pid, or of the current process if not given:
-
.initgroups(username, gid) ⇒ Array
mod_func
Sets the supplemental group access list; the new list includes:
-
.kill(signal, *ids) ⇒ count
mod_func
Sends a signal to each process specified by
ids
(which must specify at least one ID); returns the count of signals sent. -
.pid ⇒ Integer
mod_func
Returns the process ID of the current process:
-
.ppid ⇒ Integer
mod_func
Returns the process ID of the parent of the current process:
-
.setpgid(pid, pgid) ⇒ 0
mod_func
Sets the process group ID for the process given by process ID .pid to
pgid
. -
.setpgrp ⇒ 0
mod_func
Equivalent to
setpgid(0, 0)
. -
.setpriority(kind, integer, priority) ⇒ 0
mod_func
See .getpriority.
-
.setproctitle(string) ⇒ String
mod_func
Sets the process title that appears on the ps(1) command.
-
.setrlimit(resource, cur_limit, max_limit = cur_limit) ⇒ nil
mod_func
Sets limits for the current process for the given
resource
tocur_limit
(soft limit) andmax_limit
(hard limit); returnsnil
. -
.setsid ⇒ Integer
mod_func
Establishes the current process as a new session and process group leader, with no controlling tty; returns the session ID:
-
.times ⇒ Process
mod_func
Returns a
Tms
structure that contains user and system CPU times for the current process, and for its children processes: -
.wait(pid = -1, flags = 0) ⇒ Integer
(also: .waitpid)
mod_func
Waits for a suitable child process to exit, returns its process ID, and sets
$?
to aStatus
object containing information on that process. - .wait2(pid = -1, flags = 0) ⇒ Array, status (also: .waitpid2) mod_func
-
.waitall ⇒ Array
mod_func
Waits for all children, returns an array of 2-element arrays; each subarray contains the integer pid and
Status
status for one of the reaped child processes: -
.waitpid(pid = -1, flags = 0) ⇒ Integer
mod_func
Alias for .wait.
-
.waitpid2(pid = -1, flags = 0) ⇒ Array, status
mod_func
Alias for .wait2.
-
.warmup ⇒ true
mod_func
Notify the Ruby virtual machine that the boot sequence is finished, and that now is a good time to optimize the application.
Class Attribute Details
Returns the effective user ID for the current process.
Process.euid # => 501
# File 'process.c', line 7308
static VALUE proc_geteuid(VALUE obj) { rb_uid_t euid = geteuid(); return UIDT2NUM(euid); }
.euid=(new_euid) ⇒ new_euid
(rw, mod_func)
Sets the effective user ID for the current process.
Not available on all platforms.
# File 'process.c', line 7348
static VALUE proc_seteuid_m(VALUE mod, VALUE euid) { check_uid_switch(); proc_seteuid(OBJ2UID(euid)); return euid; }
Returns the (real) group ID for the current process:
Process.gid # => 1000
# File 'process.c', line 6737
static VALUE proc_getgid(VALUE obj) { rb_gid_t gid = getgid(); return GIDT2NUM(gid); }
.gid=(new_gid) ⇒ new_gid
(rw, mod_func)
Sets the group ID for the current process to new_gid
:
Process.gid = 1000 # => 1000
# File 'process.c', line 6756
static VALUE proc_setgid(VALUE obj, VALUE id) { rb_gid_t gid; check_gid_switch(); gid = OBJ2GID(id); #if defined(HAVE_SETRESGID) if (setresgid(gid, -1, -1) < 0) rb_sys_fail(0); #elif defined HAVE_SETREGID if (setregid(gid, -1) < 0) rb_sys_fail(0); #elif defined HAVE_SETRGID if (setrgid(gid) < 0) rb_sys_fail(0); #elif defined HAVE_SETGID { if (getegid() == gid) { if (setgid(gid) < 0) rb_sys_fail(0); } else { rb_notimplement(); } } #endif return GIDT2NUM(gid); }
.groups ⇒ Array (rw, mod_func)
Returns an array of the group IDs in the supplemental group access list for the current process:
Process.groups # => [4, 24, 27, 30, 46, 122, 135, 136, 1000]
These properties of the returned array are system-dependent:
-
Whether (and how) the array is sorted.
-
Whether the array includes effective group IDs.
-
Whether the array includes duplicate group IDs.
-
Whether the array size exceeds the value of .maxgroups.
Use this call to get a sorted and unique array:
Process.groups.uniq.sort
# File 'process.c', line 6857
static VALUE proc_getgroups(VALUE obj) { VALUE ary, tmp; int i, ngroups; rb_gid_t *groups; ngroups = getgroups(0, NULL); if (ngroups == -1) rb_sys_fail(0); groups = ALLOCV_N(rb_gid_t, tmp, ngroups); ngroups = getgroups(ngroups, groups); if (ngroups == -1) rb_sys_fail(0); ary = rb_ary_new(); for (i = 0; i < ngroups; i++) rb_ary_push(ary, GIDT2NUM(groups[i])); ALLOCV_END(tmp); return ary; }
.groups=(new_groups) ⇒ new_groups
(rw, mod_func)
# File 'process.c', line 6901
static VALUE proc_setgroups(VALUE obj, VALUE ary) { int ngroups, i; rb_gid_t *groups; VALUE tmp; PREPARE_GETGRNAM; Check_Type(ary, T_ARRAY); ngroups = RARRAY_LENINT(ary); if (ngroups > maxgroups()) rb_raise(rb_eArgError, "too many groups, %d max", maxgroups()); groups = ALLOCV_N(rb_gid_t, tmp, ngroups); for (i = 0; i < ngroups; i++) { VALUE g = RARRAY_AREF(ary, i); groups[i] = OBJ2GID1(g); } FINISH_GETGRNAM; if (setgroups(ngroups, groups) == -1) /* ngroups <= maxgroups */ rb_sys_fail(0); ALLOCV_END(tmp); return proc_getgroups(obj); }
.maxgroups ⇒ Integer (rw, mod_func)
Returns the maximum number of group IDs allowed in the supplemental group access list:
Process.maxgroups # => 32
# File 'process.c', line 6980
static VALUE proc_getmaxgroups(VALUE obj) { return INT2FIX(maxgroups()); }
.maxgroups=(new_max) ⇒ new_max
(rw, mod_func)
Sets the maximum number of group IDs allowed in the supplemental group access list.
# File 'process.c', line 6998
static VALUE proc_setmaxgroups(VALUE obj, VALUE val) { int ngroups = FIX2INT(val); int ngroups_max = get_sc_ngroups_max(); if (ngroups <= 0) rb_raise(rb_eArgError, "maxgroups %d should be positive", ngroups); if (ngroups > RB_MAX_GROUPS) ngroups = RB_MAX_GROUPS; if (ngroups_max > 0 && ngroups > ngroups_max) ngroups = ngroups_max; _maxgroups = ngroups; return INT2FIX(_maxgroups); }
Returns the (real) user ID of the current process.
Process.uid # => 1000
# File 'process.c', line 6335
static VALUE proc_getuid(VALUE obj) { rb_uid_t uid = getuid(); return UIDT2NUM(uid); }
.uid=(new_uid) ⇒ new_uid
(rw, mod_func)
Sets the (user) user ID for the current process to new_uid
:
Process.uid = 1000 # => 1000
Not available on all platforms.
# File 'process.c', line 6355
static VALUE proc_setuid(VALUE obj, VALUE id) { rb_uid_t uid; check_uid_switch(); uid = OBJ2UID(id); #if defined(HAVE_SETRESUID) if (setresuid(uid, -1, -1) < 0) rb_sys_fail(0); #elif defined HAVE_SETREUID if (setreuid(uid, -1) < 0) rb_sys_fail(0); #elif defined HAVE_SETRUID if (setruid(uid) < 0) rb_sys_fail(0); #elif defined HAVE_SETUID { if (geteuid() == uid) { if (setuid(uid) < 0) rb_sys_fail(0); } else { rb_notimplement(); } } #endif return id; }
Class Method Details
._fork ⇒ Integer
An internal API for fork. Do not call this method directly. Currently, this is called via Kernel.fork, .fork, and IO.popen with "-"
.
This method is not for casual code but for application monitoring libraries. You can add custom code before and after fork events by overriding this method.
Note: .daemon may be implemented using fork(2) BUT does not go through this method. Thus, depending on your reason to hook into this method, you may also want to hook into that one. See this issue for a more detailed discussion of this.
# File 'process.c', line 4304
VALUE rb_proc__fork(VALUE _obj) { rb_pid_t pid = proc_fork_pid(); return PIDT2NUM(pid); }
.abort
Alias for Kernel.abort.
.argv0 ⇒ frozen_string
(mod_func)
Returns the name of the script being executed. The value is not affected by assigning a new value to $0.
This method first appeared in Ruby 2.1 to serve as a global variable free means to get the script name.
# File 'ruby.c', line 2941
static VALUE proc_argv0(VALUE process) { return rb_orig_progname; }
.clock_getres(clock_id, unit = :float_second) ⇒ Numeric (mod_func)
Returns a clock resolution as determined by POSIX function clock_getres():
Process.clock_getres(:CLOCK_REALTIME) # => 1.0e-09
See .clock_gettime for the values of clock_id
and unit
.
Examples:
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond) # => 0.001
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond) # => 1.0e-06
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 1.0e-09
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :microsecond) # => 0
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :millisecond) # => 0
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond) # => 1
Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :second) # => 0
In addition to the values for unit
supported in .clock_gettime, this method supports :hertz
, the integer number of clock ticks per second (which is the reciprocal of :float_second
):
Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz) # => 100.0
Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 0.01
Accuracy: Note that the returned resolution may be inaccurate on some platforms due to underlying bugs. Inaccurate resolutions have been reported for various clocks including :CLOCK_MONOTONIC
and :CLOCK_MONOTONIC_RAW
on Linux, macOS, BSD or AIX platforms, when using ARM processors, or when using virtualization.
# File 'process.c', line 8581
static VALUE rb_clock_getres(int argc, VALUE *argv, VALUE _) { int ret; struct timetick tt; timetick_int_t numerators[2]; timetick_int_t denominators[2]; int num_numerators = 0; int num_denominators = 0; #ifdef HAVE_CLOCK_GETRES clockid_t c; #endif VALUE unit = (rb_check_arity(argc, 1, 2) == 2) ? argv[1] : Qnil; VALUE clk_id = argv[0]; if (SYMBOL_P(clk_id)) { #ifdef CLOCK_REALTIME if (clk_id == RUBY_CLOCK_REALTIME) { c = CLOCK_REALTIME; goto getres; } #endif #ifdef CLOCK_MONOTONIC if (clk_id == RUBY_CLOCK_MONOTONIC) { c = CLOCK_MONOTONIC; goto getres; } #endif #ifdef CLOCK_PROCESS_CPUTIME_ID if (clk_id == RUBY_CLOCK_PROCESS_CPUTIME_ID) { c = CLOCK_PROCESS_CPUTIME_ID; goto getres; } #endif #ifdef CLOCK_THREAD_CPUTIME_ID if (clk_id == RUBY_CLOCK_THREAD_CPUTIME_ID) { c = CLOCK_THREAD_CPUTIME_ID; goto getres; } #endif #ifdef RUBY_GETTIMEOFDAY_BASED_CLOCK_REALTIME if (clk_id == RUBY_GETTIMEOFDAY_BASED_CLOCK_REALTIME) { tt.giga_count = 0; tt.count = 1000; denominators[num_denominators++] = 1000000000; goto success; } #endif #ifdef RUBY_TIME_BASED_CLOCK_REALTIME if (clk_id == RUBY_TIME_BASED_CLOCK_REALTIME) { tt.giga_count = 1; tt.count = 0; denominators[num_denominators++] = 1000000000; goto success; } #endif #ifdef RUBY_TIMES_BASED_CLOCK_MONOTONIC if (clk_id == RUBY_TIMES_BASED_CLOCK_MONOTONIC) { tt.count = 1; tt.giga_count = 0; denominators[num_denominators++] = get_clk_tck(); goto success; } #endif #ifdef RUBY_GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID if (clk_id == RUBY_GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID) { tt.giga_count = 0; tt.count = 1000; denominators[num_denominators++] = 1000000000; goto success; } #endif #ifdef RUBY_TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID if (clk_id == RUBY_TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID) { tt.count = 1; tt.giga_count = 0; denominators[num_denominators++] = get_clk_tck(); goto success; } #endif #ifdef RUBY_CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID if (clk_id == RUBY_CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID) { tt.count = 1; tt.giga_count = 0; denominators[num_denominators++] = CLOCKS_PER_SEC; goto success; } #endif #ifdef RUBY_MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC if (clk_id == RUBY_MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC) { const mach_timebase_info_data_t *info = get_mach_timebase_info(); tt.count = 1; tt.giga_count = 0; numerators[num_numerators++] = info->numer; denominators[num_denominators++] = info->denom; denominators[num_denominators++] = 1000000000; goto success; } #endif } else if (NUMERIC_CLOCKID) { #if defined(HAVE_CLOCK_GETRES) struct timespec ts; c = NUM2CLOCKID(clk_id); getres: ret = clock_getres(c, &ts); if (ret == -1) clock_failed("getres", errno, clk_id); tt.count = (int32_t)ts.tv_nsec; tt.giga_count = ts.tv_sec; denominators[num_denominators++] = 1000000000; goto success; #endif } else { rb_unexpected_type(clk_id, T_SYMBOL); } clock_failed("getres", EINVAL, clk_id); success: if (unit == ID2SYM(id_hertz)) { return timetick2dblnum_reciprocal(&tt, numerators, num_numerators, denominators, num_denominators); } else { return make_clock_result(&tt, numerators, num_numerators, denominators, num_denominators, unit); } }
.clock_gettime(clock_id, unit = :float_second) ⇒ Numeric (mod_func)
Returns a clock time as determined by POSIX function clock_gettime():
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID) # => 198.650379677
Argument clock_id
should be a symbol or a constant that specifies the clock whose time is to be returned; see below.
Optional argument unit
should be a symbol that specifies the unit to be used in the returned clock time; see below.
Argument clock_id
Argument clock_id
specifies the clock whose time is to be returned; it may be a constant such as CLOCK_REALTIME, or a symbol shorthand such as :CLOCK_REALTIME
.
The supported clocks depend on the underlying operating system; this method supports the following clocks on the indicated platforms (raises Errno::EINVAL
if called with an unsupported clock):
-
:CLOCK_BOOTTIME
: Linux 2.6.39. -
:CLOCK_BOOTTIME_ALARM
: Linux 3.0. -
:CLOCK_MONOTONIC
: SUSv3 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 3.4, macOS 10.12, Windows-2000. -
:CLOCK_MONOTONIC_COARSE
: Linux 2.6.32. -
:CLOCK_MONOTONIC_FAST
: FreeBSD 8.1. -
:CLOCK_MONOTONIC_PRECISE
: FreeBSD 8.1. -
:CLOCK_MONOTONIC_RAW
: Linux 2.6.28, macOS 10.12. -
:CLOCK_MONOTONIC_RAW_APPROX
: macOS 10.12. -
:CLOCK_PROCESS_CPUTIME_ID
: SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3, OpenBSD 5.4, macOS 10.12. -
:CLOCK_PROF
: FreeBSD 3.0, OpenBSD 2.1. -
:CLOCK_REALTIME
: SUSv2 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 2.1, macOS 10.12, Windows-8/Server-2012. Time.now is recommended over +:CLOCK_REALTIME:. -
:CLOCK_REALTIME_ALARM
: Linux 3.0. -
:CLOCK_REALTIME_COARSE
: Linux 2.6.32. -
:CLOCK_REALTIME_FAST
: FreeBSD 8.1. -
:CLOCK_REALTIME_PRECISE
: FreeBSD 8.1. -
:CLOCK_SECOND
: FreeBSD 8.1. -
:CLOCK_TAI
: Linux 3.10. -
:CLOCK_THREAD_CPUTIME_ID
: SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD 5.4, macOS 10.12. -
:CLOCK_UPTIME
: FreeBSD 7.0, OpenBSD 5.5. -
:CLOCK_UPTIME_FAST
: FreeBSD 8.1. -
:CLOCK_UPTIME_PRECISE
: FreeBSD 8.1. -
:CLOCK_UPTIME_RAW
: macOS 10.12. -
:CLOCK_UPTIME_RAW_APPROX
: macOS 10.12. -
:CLOCK_VIRTUAL
: FreeBSD 3.0, OpenBSD 2.1.
Note that SUS stands for Single Unix Specification. SUS contains POSIX and clock_gettime is defined in the POSIX part. SUS defines :CLOCK_REALTIME
as mandatory but :CLOCK_MONOTONIC
, :CLOCK_PROCESS_CPUTIME_ID
, and :CLOCK_THREAD_CPUTIME_ID
are optional.
Certain emulations are used when the given clock_id
is not supported directly:
-
Emulations for
:CLOCK_REALTIME
:-
:GETTIMEOFDAY_BASED_CLOCK_REALTIME
: Use gettimeofday() defined by SUS (deprecated in SUSv4). The resolution is 1 microsecond. -
:TIME_BASED_CLOCK_REALTIME
: Use time() defined by ISO C. The resolution is 1 second.
-
-
Emulations for
:CLOCK_MONOTONIC
:-
:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC
: Use mach_absolute_time(), available on Darwin. The resolution is CPU dependent. -
:TIMES_BASED_CLOCK_MONOTONIC
: Use the result value of times() defined by POSIX, thus:Upon successful completion, times() shall return the elapsed real time, in clock ticks, since an arbitrary point in the past (for example, system start-up time).
For example, GNU/Linux returns a value based on jiffies and it is monotonic. However, 4.4BSD uses gettimeofday() and it is not monotonic. (FreeBSD uses
:CLOCK_MONOTONIC
instead, though.)The resolution is the clock tick. “getconf CLK_TCK” command shows the clock ticks per second. (The clock ticks-per-second is defined by HZ macro in older systems.) If it is 100 and clock_t is 32 bits integer type, the resolution is 10 millisecond and cannot represent over 497 days.
-
-
Emulations for
:CLOCK_PROCESS_CPUTIME_ID
:-
:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID
: Use getrusage() defined by SUS. getrusage() is used with RUSAGE_SELF to obtain the time only for the calling process (excluding the time for child processes). The result is addition of user time (ru_utime) and system time (ru_stime). The resolution is 1 microsecond. -
:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID
: Use times() defined by POSIX. The result is addition of user time (tms_utime) and system time (tms_stime). tms_cutime and tms_cstime are ignored to exclude the time for child processes. The resolution is the clock tick. “getconf CLK_TCK” command shows the clock ticks per second. (The clock ticks per second is defined by HZ macro in older systems.) If it is 100, the resolution is 10 millisecond. -
:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID
: Use clock() defined by ISO C. The resolution is1/CLOCKS_PER_SEC
.CLOCKS_PER_SEC
is the C-level macro defined by time.h. SUS definesCLOCKS_PER_SEC
as 1000000; other systems may define it differently. IfCLOCKS_PER_SEC
is 1000000 (as in SUS), the resolution is 1 microsecond. IfCLOCKS_PER_SEC
is 1000000 and clock_t is a 32-bit integer type, it cannot represent over 72 minutes.
-
Argument unit
Optional argument unit
(default :float_second
) specifies the unit for the returned value.
-
:float_microsecond
: Number of microseconds as a float. -
:float_millisecond
: Number of milliseconds as a float. -
:float_second
: Number of seconds as a float. -
:microsecond
: Number of microseconds as an integer. -
:millisecond
: Number of milliseconds as an integer. -
:nanosecond
: Number of nanoseconds as an integer. -
::second
: Number of seconds as an integer.
Examples:
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond)
# => 203605054.825
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond)
# => 203643.696848
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_second)
# => 203.762181929
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :microsecond)
# => 204123212
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :millisecond)
# => 204298
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond)
# => 204602286036
Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :second)
# => 204
The underlying function, clock_gettime(), returns a number of nanoseconds. ::Float
object (IEEE 754 double) is not enough to represent the return value for :CLOCK_REALTIME
. If the exact nanoseconds value is required, use :nanosecond
as the unit
.
The origin (time zero) of the returned value is system-dependent, and may be, for example, system start up time, process start up time, the Epoch, etc.
The origin in :CLOCK_REALTIME
is defined as the Epoch: 1970-01-01 00:00:00 UTC
; some systems count leap seconds and others don’t, so the result may vary across systems.
# File 'process.c', line 8354
static VALUE rb_clock_gettime(int argc, VALUE *argv, VALUE _) { int ret; struct timetick tt; timetick_int_t numerators[2]; timetick_int_t denominators[2]; int num_numerators = 0; int num_denominators = 0; VALUE unit = (rb_check_arity(argc, 1, 2) == 2) ? argv[1] : Qnil; VALUE clk_id = argv[0]; #ifdef HAVE_CLOCK_GETTIME clockid_t c; #endif if (SYMBOL_P(clk_id)) { #ifdef CLOCK_REALTIME if (clk_id == RUBY_CLOCK_REALTIME) { c = CLOCK_REALTIME; goto gettime; } #endif #ifdef CLOCK_MONOTONIC if (clk_id == RUBY_CLOCK_MONOTONIC) { c = CLOCK_MONOTONIC; goto gettime; } #endif #ifdef CLOCK_PROCESS_CPUTIME_ID if (clk_id == RUBY_CLOCK_PROCESS_CPUTIME_ID) { c = CLOCK_PROCESS_CPUTIME_ID; goto gettime; } #endif #ifdef CLOCK_THREAD_CPUTIME_ID if (clk_id == RUBY_CLOCK_THREAD_CPUTIME_ID) { c = CLOCK_THREAD_CPUTIME_ID; goto gettime; } #endif /* * Non-clock_gettime clocks are provided by symbol clk_id. */ #ifdef HAVE_GETTIMEOFDAY /* * GETTIMEOFDAY_BASED_CLOCK_REALTIME is used for * CLOCK_REALTIME if clock_gettime is not available. */ #define RUBY_GETTIMEOFDAY_BASED_CLOCK_REALTIME ID2SYM(id_GETTIMEOFDAY_BASED_CLOCK_REALTIME) if (clk_id == RUBY_GETTIMEOFDAY_BASED_CLOCK_REALTIME) { struct timeval tv; ret = gettimeofday(&tv, 0); if (ret != 0) rb_sys_fail("gettimeofday"); tt.giga_count = tv.tv_sec; tt.count = (int32_t)tv.tv_usec * 1000; denominators[num_denominators++] = 1000000000; goto success; } #endif #define RUBY_TIME_BASED_CLOCK_REALTIME ID2SYM(id_TIME_BASED_CLOCK_REALTIME) if (clk_id == RUBY_TIME_BASED_CLOCK_REALTIME) { time_t t; t = time(NULL); if (t == (time_t)-1) rb_sys_fail("time"); tt.giga_count = t; tt.count = 0; denominators[num_denominators++] = 1000000000; goto success; } #ifdef HAVE_TIMES #define RUBY_TIMES_BASED_CLOCK_MONOTONIC \ ID2SYM(id_TIMES_BASED_CLOCK_MONOTONIC) if (clk_id == RUBY_TIMES_BASED_CLOCK_MONOTONIC) { struct tms buf; clock_t c; unsigned_clock_t uc; c = times(&buf); if (c == (clock_t)-1) rb_sys_fail("times"); uc = (unsigned_clock_t)c; tt.count = (int32_t)(uc % 1000000000); tt.giga_count = (uc / 1000000000); denominators[num_denominators++] = get_clk_tck(); goto success; } #endif #ifdef RUSAGE_SELF #define RUBY_GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID \ ID2SYM(id_GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID) if (clk_id == RUBY_GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID) { struct rusage usage; int32_t usec; ret = getrusage(RUSAGE_SELF, &usage); if (ret != 0) rb_sys_fail("getrusage"); tt.giga_count = usage.ru_utime.tv_sec + usage.ru_stime.tv_sec; usec = (int32_t)(usage.ru_utime.tv_usec + usage.ru_stime.tv_usec); if (1000000 <= usec) { tt.giga_count++; usec -= 1000000; } tt.count = usec * 1000; denominators[num_denominators++] = 1000000000; goto success; } #endif #ifdef HAVE_TIMES #define RUBY_TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID \ ID2SYM(id_TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID) if (clk_id == RUBY_TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID) { struct tms buf; unsigned_clock_t utime, stime; if (times(&buf) == (clock_t)-1) rb_sys_fail("times"); utime = (unsigned_clock_t)buf.tms_utime; stime = (unsigned_clock_t)buf.tms_stime; tt.count = (int32_t)((utime % 1000000000) + (stime % 1000000000)); tt.giga_count = (utime / 1000000000) + (stime / 1000000000); if (1000000000 <= tt.count) { tt.count -= 1000000000; tt.giga_count++; } denominators[num_denominators++] = get_clk_tck(); goto success; } #endif #define RUBY_CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID \ ID2SYM(id_CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID) if (clk_id == RUBY_CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID) { clock_t c; unsigned_clock_t uc; errno = 0; c = clock(); if (c == (clock_t)-1) rb_sys_fail("clock"); uc = (unsigned_clock_t)c; tt.count = (int32_t)(uc % 1000000000); tt.giga_count = uc / 1000000000; denominators[num_denominators++] = CLOCKS_PER_SEC; goto success; } #ifdef __APPLE__ if (clk_id == RUBY_MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC) { const mach_timebase_info_data_t *info = get_mach_timebase_info(); uint64_t t = mach_absolute_time(); tt.count = (int32_t)(t % 1000000000); tt.giga_count = t / 1000000000; numerators[num_numerators++] = info->numer; denominators[num_denominators++] = info->denom; denominators[num_denominators++] = 1000000000; goto success; } #endif } else if (NUMERIC_CLOCKID) { #if defined(HAVE_CLOCK_GETTIME) struct timespec ts; c = NUM2CLOCKID(clk_id); gettime: ret = clock_gettime(c, &ts); if (ret == -1) clock_failed("gettime", errno, clk_id); tt.count = (int32_t)ts.tv_nsec; tt.giga_count = ts.tv_sec; denominators[num_denominators++] = 1000000000; goto success; #endif } else { rb_unexpected_type(clk_id, T_SYMBOL); } clock_failed("gettime", EINVAL, clk_id); success: return make_clock_result(&tt, numerators, num_numerators, denominators, num_denominators, unit); }
.daemon(nochdir = nil, noclose = nil) ⇒ 0
(mod_func)
Detaches the current process from its controlling terminal and runs it in the background as system daemon; returns zero.
By default:
-
Changes the current working directory to the root directory.
-
Redirects $stdin, $stdout, and $stderr to the null device.
If optional argument nochdir
is true
, does not change the current working directory.
If optional argument noclose
is true
, does not redirect $stdin, $stdout, or $stderr.
# File 'process.c', line 7044
static VALUE proc_daemon(int argc, VALUE *argv, VALUE _) { int n, nochdir = FALSE, noclose = FALSE; switch (rb_check_arity(argc, 0, 2)) { case 2: noclose = TO_BOOL(argv[1], "noclose"); case 1: nochdir = TO_BOOL(argv[0], "nochdir"); } prefork(); n = rb_daemon(nochdir, noclose); if (n < 0) rb_sys_fail("daemon"); return INT2FIX(n); }
.detach(pid) ⇒ Thread (mod_func)
Avoids the potential for a child process to become a zombie process. detach
prevents this by setting up a separate Ruby thread whose sole job is to reap the status of the process pid when it terminates.
This method is needed only when the parent process will never wait for the child process.
This example does not reap the second child process; that process appears as a zombie in the process status (ps
) output:
pid = Process.spawn('ruby', '-e', 'exit 13') # => 312691
sleep(1)
# Find zombies.
system("ps -ho pid,state -p #{pid}")
Output:
312716 Z
This example also does not reap the second child process, but it does detach the process so that it does not become a zombie:
pid = Process.spawn('ruby', '-e', 'exit 13') # => 313213
thread = Process.detach(pid)
sleep(1)
# => #<Process::Waiter:0x00007f038f48b838 run>
system("ps -ho pid,state -p #{pid}") # Finds no zombies.
The waiting thread can return the pid of the detached child process:
thread.join.pid # => 313262
# File 'process.c', line 1601
static VALUE proc_detach(VALUE obj, VALUE pid) { return rb_detach_process(NUM2PIDT(pid)); }
Returns the effective group ID for the current process:
Process.egid # => 500
Not available on all platforms.
# File 'process.c', line 7434
static VALUE proc_getegid(VALUE obj) { rb_gid_t egid = getegid(); return GIDT2NUM(egid); }
.egid=(new_egid) ⇒ new_egid
(mod_func)
Sets the effective group ID for the current process.
Not available on all platforms.
# File 'process.c', line 7452
static VALUE proc_setegid(VALUE obj, VALUE egid) { #if defined(HAVE_SETRESGID) || defined(HAVE_SETREGID) || defined(HAVE_SETEGID) || defined(HAVE_SETGID) rb_gid_t gid; #endif check_gid_switch(); #if defined(HAVE_SETRESGID) || defined(HAVE_SETREGID) || defined(HAVE_SETEGID) || defined(HAVE_SETGID) gid = OBJ2GID(egid); #endif #if defined(HAVE_SETRESGID) if (setresgid(-1, gid, -1) < 0) rb_sys_fail(0); #elif defined HAVE_SETREGID if (setregid(-1, gid) < 0) rb_sys_fail(0); #elif defined HAVE_SETEGID if (setegid(gid) < 0) rb_sys_fail(0); #elif defined HAVE_SETGID if (gid == getgid()) { if (setgid(gid) < 0) rb_sys_fail(0); } else { rb_notimplement(); } #else rb_notimplement(); #endif return egid; }
.exec([env, ] command_line, options = {})
.exec([env, ] exe_path, *args, options = {})
Alias for Kernel.exec.
.exit(status = true)
Alias for Kernel.exit.
.exit!(status = false)
Alias for Kernel.exit!.
.fork
Alias for Kernel.fork.
.getpgid(pid) ⇒ Integer (mod_func)
# File 'process.c', line 5145
static VALUE proc_getpgid(VALUE obj, VALUE pid) { rb_pid_t i; i = getpgid(NUM2PIDT(pid)); if (i < 0) rb_sys_fail(0); return PIDT2NUM(i); }
.getpgrp ⇒ Integer (mod_func)
Returns the process group ID for the current process:
Process.getpgid(0) # => 25527
Process.getpgrp # => 25527
# File 'process.c', line 5084
static VALUE proc_getpgrp(VALUE _) { rb_pid_t pgrp; #if defined(HAVE_GETPGRP) && defined(GETPGRP_VOID) pgrp = getpgrp(); if (pgrp < 0) rb_sys_fail(0); return PIDT2NUM(pgrp); #else /* defined(HAVE_GETPGID) */ pgrp = getpgid(0); if (pgrp < 0) rb_sys_fail(0); return PIDT2NUM(pgrp); #endif }
.getpriority(kind, id) ⇒ Integer (mod_func)
Returns the scheduling priority for specified process, process group, or user.
Argument kind
is one of:
-
PRIO_PROCESS: return priority for process.
-
PRIO_PGRP: return priority for process group.
-
PRIO_USER: return priority for user.
Argument id
is the ID for the process, process group, or user; zero specified the current ID for kind
.
Examples:
Process.getpriority(Process::PRIO_USER, 0) # => 19
Process.getpriority(Process::PRIO_PROCESS, 0) # => 19
Not available on all platforms.
# File 'process.c', line 5303
static VALUE proc_getpriority(VALUE obj, VALUE which, VALUE who) { int prio, iwhich, iwho; iwhich = NUM2INT(which); iwho = NUM2INT(who); errno = 0; prio = getpriority(iwhich, iwho); if (errno) rb_sys_fail(0); return INT2FIX(prio); }
.getrlimit(resource) ⇒ Array, max_limit
(mod_func)
Returns a 2-element array of the current (soft) limit and maximum (hard) limit for the given resource
.
Argument resource
specifies the resource whose limits are to be returned; see .setrlimit.
Each of the returned values cur_limit
and max_limit
is an integer; see .setrlimit.
Example:
Process.getrlimit(:CORE) # => [0, 18446744073709551615]
See .setrlimit.
Not available on all platforms.
# File 'process.c', line 5603
static VALUE proc_getrlimit(VALUE obj, VALUE resource) { struct rlimit rlim; if (getrlimit(rlimit_resource_type(resource), &rlim) < 0) { rb_sys_fail("getrlimit"); } return rb_assoc_new(RLIM2NUM(rlim.rlim_cur), RLIM2NUM(rlim.rlim_max)); }
.getsid(pid = nil) ⇒ Integer (mod_func)
# File 'process.c', line 5200
static VALUE proc_getsid(int argc, VALUE *argv, VALUE _) { rb_pid_t sid; rb_pid_t pid = 0; if (rb_check_arity(argc, 0, 1) == 1 && !NIL_P(argv[0])) pid = NUM2PIDT(argv[0]); sid = getsid(pid); if (sid < 0) rb_sys_fail(0); return PIDT2NUM(sid); }
.initgroups(username, gid) ⇒ Array (mod_func)
Sets the supplemental group access list; the new list includes:
-
The group IDs of those groups to which the user given by
username
belongs. -
The group ID .gid.
Example:
Process.groups # => [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
Process.initgroups('me', 30) # => [30, 6, 10, 11]
Process.groups # => [30, 6, 10, 11]
Not available on all platforms.
# File 'process.c', line 6956
static VALUE proc_initgroups(VALUE obj, VALUE uname, VALUE base_grp) { if (initgroups(StringValueCStr(uname), OBJ2GID(base_grp)) != 0) { rb_sys_fail(0); } return proc_getgroups(obj); }
.kill(signal, *ids) ⇒ count
(mod_func)
Sends a signal to each process specified by ids
(which must specify at least one ID); returns the count of signals sent.
For each given id
, if id
is:
-
Positive, sends the signal to the process whose process ID is
id
. -
Zero, send the signal to all processes in the current process group.
-
Negative, sends the signal to a system-dependent collection of processes.
Argument signal
specifies the signal to be sent; the argument may be:
-
An integer signal number: e.g.,
-29
,0
,29
. -
A signal name (string), with or without leading
'SIG'
, and with or without a further prefixed minus sign ('-'
): e.g.:-
'SIGPOLL'
. -
'POLL'
, -
'-SIGPOLL'
. -
'-POLL'
.
-
-
A signal symbol, with or without leading
'SIG'
, and with or without a further prefixed minus sign ('-'
): e.g.:-
:SIGPOLL
. -
:POLL
. -
:'-SIGPOLL'
. -
:'-POLL'
.
-
If signal
is:
-
A non-negative integer, or a signal name or symbol without prefixed
'-'
, each process with process IDid
is signalled. -
A negative integer, or a signal name or symbol with prefixed
'-'
, each process group with group IDid
is signalled.
Use method Signal.list to see which signals are supported by Ruby on the underlying platform; the method returns a hash of the string names and non-negative integer values of the supported signals. The size and content of the returned hash varies widely among platforms.
Additionally, signal 0
is useful to determine if the process exists.
Example:
pid = fork do
Signal.trap('HUP') { puts 'Ouch!'; exit }
# ... do some work ...
end
# ...
Process.kill('HUP', pid)
Process.wait
Output:
Ouch!
Exceptions:
-
Raises
Errno::EINVAL
or::RangeError
ifsignal
is an integer but invalid. -
Raises ArgumentError if
signal
is a string or symbol but invalid. -
Raises
Errno::ESRCH
or::RangeError
if one ofids
is invalid. -
Raises
Errno::EPERM
if needed permissions are not in force.
In the last two cases, signals may have been sent to some processes.
# File 'process.c', line 8813
static VALUE proc_rb_f_kill(int c, const VALUE *v, VALUE _) { return rb_f_kill(c, v); }
.last_status ⇒ Process
?
Returns a ::Process::Status
object representing the most recently exited child process in the current thread, or nil
if none:
Process.spawn('ruby', '-e', 'exit 13')
Process.wait
Process.last_status # => #<Process::Status: pid 14396 exit 13>
Process.spawn('ruby', '-e', 'exit 14')
Process.wait
Process.last_status # => #<Process::Status: pid 4692 exit 14>
Process.spawn('ruby', '-e', 'exit 15')
# 'exit 15' has not been reaped by #wait.
Process.last_status # => #<Process::Status: pid 4692 exit 14>
Process.wait
Process.last_status # => #<Process::Status: pid 1380 exit 15>
# File 'process.c', line 638
static VALUE proc_s_last_status(VALUE mod) { return rb_last_status_get(); }
.pid ⇒ Integer (mod_func)
Returns the process ID of the current process:
Process.pid # => 15668
# File 'process.c', line 529
static VALUE proc_get_pid(VALUE _) { return get_pid(); }
.ppid ⇒ Integer (mod_func)
# File 'process.c', line 558
static VALUE proc_get_ppid(VALUE _) { return get_ppid(); }
.setpgid(pid, pgid) ⇒ 0
(mod_func)
Sets the process group ID for the process given by process ID .pid to pgid
.
Not available on all platforms.
# File 'process.c', line 5170
static VALUE proc_setpgid(VALUE obj, VALUE pid, VALUE pgrp) { rb_pid_t ipid, ipgrp; ipid = NUM2PIDT(pid); ipgrp = NUM2PIDT(pgrp); if (setpgid(ipid, ipgrp) < 0) rb_sys_fail(0); return INT2FIX(0); }
.setpgrp ⇒ 0
(mod_func)
Equivalent to setpgid(0, 0)
.
Not available on all platforms.
# File 'process.c', line 5114
static VALUE proc_setpgrp(VALUE _) { /* check for posix setpgid() first; this matches the posix */ /* getpgrp() above. It appears that configure will set SETPGRP_VOID */ /* even though setpgrp(0,0) would be preferred. The posix call avoids */ /* this confusion. */ #ifdef HAVE_SETPGID if (setpgid(0,0) < 0) rb_sys_fail(0); #elif defined(HAVE_SETPGRP) && defined(SETPGRP_VOID) if (setpgrp() < 0) rb_sys_fail(0); #endif return INT2FIX(0); }
.setpriority(kind, integer, priority) ⇒ 0
(mod_func)
See .getpriority.
Examples:
Process.setpriority(Process::PRIO_USER, 0, 19) # => 0
Process.setpriority(Process::PRIO_PROCESS, 0, 19) # => 0
Process.getpriority(Process::PRIO_USER, 0) # => 19
Process.getpriority(Process::PRIO_PROCESS, 0) # => 19
Not available on all platforms.
# File 'process.c', line 5338
static VALUE proc_setpriority(VALUE obj, VALUE which, VALUE who, VALUE prio) { int iwhich, iwho, iprio; iwhich = NUM2INT(which); iwho = NUM2INT(who); iprio = NUM2INT(prio); if (setpriority(iwhich, iwho, iprio) < 0) rb_sys_fail(0); return INT2FIX(0); }
.setproctitle(string) ⇒ String (mod_func)
Sets the process title that appears on the ps(1) command. Not necessarily effective on all platforms. No exception will be raised regardless of the result, nor will ::NotImplementedError
be raised even if the platform does not support the feature.
Calling this method does not affect the value of $0.
Process.setproctitle('myapp: worker #%d' % worker_id)
This method first appeared in Ruby 2.1 to serve as a global variable free means to change the process title.
# File 'ruby.c', line 2966
static VALUE proc_setproctitle(VALUE process, VALUE title) { return ruby_setproctitle(title); }
.setrlimit(resource, cur_limit, max_limit = cur_limit) ⇒ nil
(mod_func)
Sets limits for the current process for the given resource
to cur_limit
(soft limit) and max_limit
(hard limit); returns nil
.
Argument resource
specifies the resource whose limits are to be set; the argument may be given as a symbol, as a string, or as a constant beginning with Process::RLIMIT_
(e.g., :CORE
, 'CORE'
, or RLIMIT_CORE.
The resources available and supported are system-dependent, and may include (here expressed as symbols):
-
:AS
: Total available memory (bytes) (SUSv3, NetBSD, FreeBSD, OpenBSD except 4.4BSD-Lite). -
:CORE
: Core size (bytes) (SUSv3). -
:CPU
: CPU time (seconds) (SUSv3). -
:DATA
:::Data
segment (bytes) (SUSv3). -
:FSIZE
:::File
size (bytes) (SUSv3). -
:MEMLOCK
: Total size for mlock(2) (bytes) (4.4BSD, GNU/Linux). -
:MSGQUEUE
: Allocation for POSIX message queues (bytes) (GNU/Linux). -
:NICE
: Ceiling on process’s nice(2) value (number) (GNU/Linux). -
:NOFILE
:::File
descriptors (number) (SUSv3). -
:NPROC
: Number of processes for the user (number) (4.4BSD, GNU/Linux). -
:NPTS
: Number of pseudo terminals (number) (FreeBSD). -
:RSS
: Resident memory size (bytes) (4.2BSD, GNU/Linux). -
:RTPRIO
: Ceiling on the process’s real-time priority (number) (GNU/Linux). -
:RTTIME
: CPU time for real-time process (us) (GNU/Linux). -
:SBSIZE
: All socket buffers (bytes) (NetBSD, FreeBSD). -
:SIGPENDING
: Number of queued signals allowed (signals) (GNU/Linux). -
:STACK
: Stack size (bytes) (SUSv3).
Arguments cur_limit
and max_limit
may be:
-
Integers (
max_limit
should not be smaller thancur_limit
). -
::Symbol
:SAVED_MAX
, string'SAVED_MAX'
, or constant RLIM_SAVED_MAX: saved maximum limit. -
::Symbol
:SAVED_CUR
, string'SAVED_CUR'
, or constant RLIM_SAVED_CUR: saved current limit. -
::Symbol
:INFINITY
, string'INFINITY'
, or constant RLIM_INFINITY: no limit on resource.
This example raises the soft limit of core size to the hard limit to try to make core dump possible:
Process.setrlimit(:CORE, Process.getrlimit(:CORE)[1])
Not available on all platforms.
# File 'process.c', line 5670
static VALUE proc_setrlimit(int argc, VALUE *argv, VALUE obj) { VALUE resource, rlim_cur, rlim_max; struct rlimit rlim; rb_check_arity(argc, 2, 3); resource = argv[0]; rlim_cur = argv[1]; if (argc < 3 || NIL_P(rlim_max = argv[2])) rlim_max = rlim_cur; rlim.rlim_cur = rlimit_resource_value(rlim_cur); rlim.rlim_max = rlimit_resource_value(rlim_max); if (setrlimit(rlimit_resource_type(resource), &rlim) < 0) { rb_sys_fail("setrlimit"); } return Qnil; }
.setsid ⇒ Integer (mod_func)
Establishes the current process as a new session and process group leader, with no controlling tty; returns the session ID:
Process.setsid # => 27422
Not available on all platforms.
# File 'process.c', line 5236
static VALUE proc_setsid(VALUE _) { rb_pid_t pid; pid = setsid(); if (pid < 0) rb_sys_fail(0); return PIDT2NUM(pid); }
Alias for Kernel.spawn.
.times ⇒ Process
(mod_func)
Returns a ::Process::Tms
structure that contains user and system CPU times for the current process, and for its children processes:
Process.times
# => #<struct Process::Tms utime=55.122118, stime=35.533068, cutime=0.0, cstime=0.002846>
The precision is platform-defined.
# File 'process.c', line 7933
VALUE rb_proc_times(VALUE obj) { VALUE utime, stime, cutime, cstime, ret; #if defined(RUSAGE_SELF) && defined(RUSAGE_CHILDREN) struct rusage usage_s, usage_c; if (getrusage(RUSAGE_SELF, &usage_s) != 0 || getrusage(RUSAGE_CHILDREN, &usage_c) != 0) rb_sys_fail("getrusage"); utime = DBL2NUM((double)usage_s.ru_utime.tv_sec + (double)usage_s.ru_utime.tv_usec/1e6); stime = DBL2NUM((double)usage_s.ru_stime.tv_sec + (double)usage_s.ru_stime.tv_usec/1e6); cutime = DBL2NUM((double)usage_c.ru_utime.tv_sec + (double)usage_c.ru_utime.tv_usec/1e6); cstime = DBL2NUM((double)usage_c.ru_stime.tv_sec + (double)usage_c.ru_stime.tv_usec/1e6); #else const double hertz = (double)get_clk_tck(); struct tms buf; times(&buf); utime = DBL2NUM(buf.tms_utime / hertz); stime = DBL2NUM(buf.tms_stime / hertz); cutime = DBL2NUM(buf.tms_cutime / hertz); cstime = DBL2NUM(buf.tms_cstime / hertz); #endif ret = rb_struct_new(rb_cProcessTms, utime, stime, cutime, cstime); RB_GC_GUARD(utime); RB_GC_GUARD(stime); RB_GC_GUARD(cutime); RB_GC_GUARD(cstime); return ret; }
.wait(pid = -1, flags = 0) ⇒ Integer (mod_func) Also known as: .waitpid
Waits for a suitable child process to exit, returns its process ID, and sets $?
to a ::Process::Status
object containing information on that process. Which child it waits for depends on the value of the given .pid:
-
Positive integer: Waits for the child process whose process ID is .pid:
pid0 = Process.spawn('ruby', '-e', 'exit 13') # => 230866 pid1 = Process.spawn('ruby', '-e', 'exit 14') # => 230891 Process.wait(pid0) # => 230866 $? # => #<Process::Status: pid 230866 exit 13> Process.wait(pid1) # => 230891 $? # => #<Process::Status: pid 230891 exit 14> Process.wait(pid0) # Raises Errno::ECHILD
-
0
: Waits for any child process whose group ID is the same as that of the current process:parent_pgpid = Process.getpgid(Process.pid) puts "Parent process group ID is #{parent_pgpid}." child0_pid = fork do puts "Child 0 pid is #{Process.pid}" child0_pgid = Process.getpgid(Process.pid) puts "Child 0 process group ID is #{child0_pgid} (same as parent's)." end child1_pid = fork do puts "Child 1 pid is #{Process.pid}" Process.setpgid(0, Process.pid) child1_pgid = Process.getpgid(Process.pid) puts "Child 1 process group ID is #{child1_pgid} (different from parent's)." end retrieved_pid = Process.wait(0) puts "Process.wait(0) returned pid #{retrieved_pid}, which is child 0 pid." begin Process.wait(0) rescue Errno::ECHILD => x puts "Raised #{x.class}, because child 1 process group ID differs from parent process group ID." end
Output:
Parent process group ID is 225764. Child 0 pid is 225788 Child 0 process group ID is 225764 (same as parent's). Child 1 pid is 225789 Child 1 process group ID is 225789 (different from parent's). Process.wait(0) returned pid 225788, which is child 0 pid. Raised Errno::ECHILD, because child 1 process group ID differs from parent process group ID.
-
-1
(default): Waits for any child process:parent_pgpid = Process.getpgid(Process.pid) puts "Parent process group ID is #{parent_pgpid}." child0_pid = fork do puts "Child 0 pid is #{Process.pid}" child0_pgid = Process.getpgid(Process.pid) puts "Child 0 process group ID is #{child0_pgid} (same as parent's)." end child1_pid = fork do puts "Child 1 pid is #{Process.pid}" Process.setpgid(0, Process.pid) child1_pgid = Process.getpgid(Process.pid) puts "Child 1 process group ID is #{child1_pgid} (different from parent's)." sleep 3 # To force child 1 to exit later than child 0 exit. end child_pids = [child0_pid, child1_pid] retrieved_pid = Process.wait(-1) puts child_pids.include?(retrieved_pid) retrieved_pid = Process.wait(-1) puts child_pids.include?(retrieved_pid)
Output:
Parent process group ID is 228736. Child 0 pid is 228758 Child 0 process group ID is 228736 (same as parent's). Child 1 pid is 228759 Child 1 process group ID is 228759 (different from parent's). true true
-
Less than
-1
: Waits for any child whose process group ID is-pid
:parent_pgpid = Process.getpgid(Process.pid) puts "Parent process group ID is #{parent_pgpid}." child0_pid = fork do puts "Child 0 pid is #{Process.pid}" child0_pgid = Process.getpgid(Process.pid) puts "Child 0 process group ID is #{child0_pgid} (same as parent's)." end child1_pid = fork do puts "Child 1 pid is #{Process.pid}" Process.setpgid(0, Process.pid) child1_pgid = Process.getpgid(Process.pid) puts "Child 1 process group ID is #{child1_pgid} (different from parent's)." end sleep 1 retrieved_pid = Process.wait(-child1_pid) puts "Process.wait(-child1_pid) returned pid #{retrieved_pid}, which is child 1 pid." begin Process.wait(-child1_pid) rescue Errno::ECHILD => x puts "Raised #{x.class}, because there's no longer a child with process group id #{child1_pid}." end
Output:
Parent process group ID is 230083. Child 0 pid is 230108 Child 0 process group ID is 230083 (same as parent's). Child 1 pid is 230109 Child 1 process group ID is 230109 (different from parent's). Process.wait(-child1_pid) returned pid 230109, which is child 1 pid. Raised Errno::ECHILD, because there's no longer a child with process group id 230109.
Argument flags
should be given as one of the following constants, or as the logical OR of both:
-
WNOHANG: Does not block if no child process is available.
-
WUNTRACED: May return a stopped child process, even if not yet reported.
Not all flags are available on all platforms.
Raises Errno::ECHILD
if there is no suitable child process.
Not available on all platforms.
.waitpid is an alias for wait
.
# File 'process.c', line 1465
static VALUE proc_m_wait(int c, VALUE *v, VALUE _) { return proc_wait(c, v); }
.wait2(pid = -1, flags = 0) ⇒ Array, status
(mod_func) Also known as: .waitpid2
# File 'process.c', line 1485
static VALUE proc_wait2(int argc, VALUE *argv, VALUE _) { VALUE pid = proc_wait(argc, argv); if (NIL_P(pid)) return Qnil; return rb_assoc_new(pid, rb_last_status_get()); }
.waitall ⇒ Array (mod_func)
Waits for all children, returns an array of 2-element arrays; each subarray contains the integer pid and ::Process::Status
status for one of the reaped child processes:
pid0 = Process.spawn('ruby', '-e', 'exit 13') # => 325470
pid1 = Process.spawn('ruby', '-e', 'exit 14') # => 325495
Process.waitall
# => [[325470, #<Process::Status: pid 325470 exit 13>], [325495, #<Process::Status: pid 325495 exit 14>]]
# File 'process.c', line 1509
static VALUE proc_waitall(VALUE _) { VALUE result; rb_pid_t pid; int status; result = rb_ary_new(); rb_last_status_clear(); for (pid = -1;;) { pid = rb_waitpid(-1, &status, 0); if (pid == -1) { int e = errno; if (e == ECHILD) break; rb_syserr_fail(e, 0); } rb_ary_push(result, rb_assoc_new(PIDT2NUM(pid), rb_last_status_get())); } return result; }
Alias for .wait.
Alias for .wait2.
.warmup ⇒ true
(mod_func)
Notify the Ruby virtual machine that the boot sequence is finished, and that now is a good time to optimize the application. This is useful for long running applications.
This method is expected to be called at the end of the application boot. If the application is deployed using a pre-forking model, warmup
should be called in the original process before the first fork.
The actual optimizations performed are entirely implementation specific and may change in the future without notice.
On CRuby, warmup
:
-
Performs a major
::GC
. -
Compacts the heap.
-
Promotes all surviving objects to the old generation.
-
Precomputes the coderange of all strings.
-
Frees all empty heap pages and increments the allocatable pages counter by the number of pages freed.
-
Invoke
malloc_trim
if available to free empty malloc pages.
# File 'process.c', line 8850
static VALUE proc_warmup(VALUE _) { RB_VM_LOCK_ENTER(); rb_gc_prepare_heap(); RB_VM_LOCK_LEAVE(); return Qtrue; }