proc-wait3 1.8.1 → 1.9.1

data/doc/wait3.txt

@@ -1,192 +0,0 @@
-== Description
-   Adds the wait3, wait4, waitid, pause, sigsend, and getrusage methods to
-   the Process module.
-
-== Synopsis
-   require 'proc/wait3'
-
-   pid = fork{ sleep 1; exit 2 }
-   p Time.now
-   Process.wait3
-   p $?
-
-== Module Methods
-Proc.pause(signals=nil)
-   Pauses the current process. If the process receives any of the signals
-   you pass as arguments it will return from the pause and continue with
-   the execution of your code. Otherwise, it will exit.
-   
-   Note that you must leave out the 'SIG' prefix for the signal name, e.g.
-   use 'INT', not 'SIGINT'.
-
-   Returns the result of the pause() function, which should always be -1.
-   
-Process.sigsend(idtype, id, signal=0)
-   Sends a signal of type "idtype" to a process or process group "id". This
-   is more versatile method of sending signals to processes than Process.kill.
-   
-   For a list of valid idtype values, see the "Process type constants" below.
-   Not supported on all platforms.
-   
-Proc.wait3(flags=0)
-   Delays its caller until a signal is received or one of its child processes
-   terminates or stops due to tracing.
-
-   The return value is a ProcStat structure and sets the $last_status global
-   variable. The special global $? is also set. Raises a SystemError if there
-   are no child processes.
-
-Proc.wait4(pid, flags=0)
-   Waits for the given child process to exit. Returns a ProcStat structure.
-   The $last_status global variable is set. Also sets the $? special global
-   variable.
-   
-Proc.waitid(id_type, id_num=nil, options=nil)
-   Suspends the calling process until one of its children changes state,
-   returning immediately if a child process changed state prior to the call.
-   The state of a child process will change if it terminates, stops because
-   of a signal, becomes trapped or reaches a breakpoint.
-
-   The id_num corresponds to a process ID or process group ID, depending on
-   the value of +id_type+, which may be Process::P_PID, Process::P_PGID or
-   Process::P_ALL. If +id_type+ is Process::P_ALL, then the +id_num+ is ignored.
-
-   The options argument is used to specify which state changes are to be
-   waited for. It is constructed from the bitwise-OR of one or more of the
-   following constants:
-
-   Process::WCONTINUED
-   Process::WEXITED
-   Process::WNOHANG
-   Process::WNOWAIT
-   Process::WSTOPPED
-   Process::WTRAPPED (not supported on all platforms)
-
-   If Process::WNOHANG is set as an option, this method will return
-   immediately, whether or not a child has changed state.
-
-   Calling this method with an +id_type+ of Process::P_ALL and the options set
-   to 'Process::EXITED | Process::WTRAPPED' is equivalent to calling
-   Process.wait.
-
-   Returns a Proc::SigInfo struct and sets $?.
-
-   Not supported on all platforms.
-
-== Constants
-=== Standard
-Process::WAIT3_VERSION
-   Returns the version of this package as a string.
-
-=== Process type constants
-==== All platforms
-Process::P_ALL
-   All non-system process.
-
-Process::P_PID
-   A standard process id.
-
-Process::P_PGID
-   Any non-system process group id.
-
-==== Not supported on all platforms
-Process::P_CID
-   A scheduler process id.
-
-Process::P_GID
-   Any non-system effective process group id.
-
-Process::P_PROJID
-   A project process id. Solaris 8 or later only.
-
-Process::P_SID
-   A session process id.
-
-Process::P_TASKID
-   A task process id. Solaris 8 or later only.
-
-Process::P_UID
-   Any non-system effective process user id.
-
-=== The following additional constants are defined if the waitid function is
-    supported on your system.
-   
-Process::WCONTINUED
-   Return the status for any child that was stopped and has been continued.
-
-Process::WEXITED
-   Wait for process(es) to exit.
-
-Process::WNOWAIT
-   Keep the process in a waitable state.
-
-Process::WSTOPPED
-   Wait for and return the process status of any child that has stopped upon
-   receipt of a signal.
-
-Process::WTRAPPED
-   Wait for traced process(es) to become trapped or reach a breakpoint.
-
-   Not supported on all platforms.
-   
-=== RLIMIT constants
-Process::RLIMIT_AS
-   A synonym for RLIMIT_VMEM
-   
-Process::RLIMIT_CORE
-   The maximum size of a core file, in bytes, that may be created.
-   
-Process::RLIMIT_CPU
-   The maximum amount of CPU time, in seconds, the process is allowed to use.
-   
-Process::RLIMIT_DATA
-   The maximum size of the process' heap size, in bytes.
-   
-Process::RLIMIT_FSIZE
-   The maximum size of a file, in bytes, that the process may create.
-   
-Process::RLIMIT_NOFILE
-   The maximum value that the kernel may assign to a file descriptor,
-   effectively limiting the number of open files for the calling process.
-   
-Process::RLIMIT_STACK
-   The maximum size of the process' stack in bytes.
-   
-Process::RLIMIT_VMEM
-   The maximum size of the process' mapped address space.
-   
-Process::RLIM_INFINITY
-   A infinite limit.
-   
-Process::RLIM_SAVED_CUR
-   Current soft limit.
-   
-Process::RLIM_SAVED_MAX
-   Current hard limit.
-
-== Notes
-   The wait3 and wait4 methods are similar to the wait2 and waitpid2
-   methods, except that they return much more information via the rusage
-   struct.
-
-== Known Bugs
-   None that I'm aware of. Please log any bugs on the Github project
-   page at https://github.com/djberg96/proc-wait3.
-
-== License
-   Apache-2.0
-
-== Copyright
-   (C) 2003-2019 Daniel J. Berger
-   All Rights Reserved.
-
-== Warranty
-   This package is provided "as is" and without any express or
-   implied warranties, including, without limitation, the implied
-   warranties of merchantability and fitness for a particular purpose.
-
-== Author
-   Daniel J. Berger
-
-== See also
-   wait3, wait4, waitid, pause, sigsend

data/test/test_proc_wait3.rb

@@ -1,227 +0,0 @@
-##################################################################
-# test_proc_wait3.rb
-#
-# Test suite for the Ruby proc-wait3 package. You should run this
-# via the 'test' rake task.
-##################################################################
-require 'proc/wait3'
-require 'test-unit'
-require 'rbconfig'
-
-class TC_Proc_Wait3 < Test::Unit::TestCase
-  def self.startup
-    @@solaris = RbConfig::CONFIG['host_os'] =~ /sunos|solaris/i
-    @@darwin  = RbConfig::CONFIG['host_os'] =~ /darwin|osx/i
-    @@hpux    = RbConfig::CONFIG['host_os'] =~ /hpux/i
-    @@linux   = RbConfig::CONFIG['host_os'] =~ /linux/i
-    @@freebsd = RbConfig::CONFIG['host_os'] =~ /bsd/i
-  end
-
-  def setup
-    @proc_stat = nil
-    @proc_stat_members = [
-      "pid", "status", "utime", "stime", "maxrss",
-      "ixrss", "idrss", "isrss", "minflt", "majflt", "nswap", "inblock",
-      "oublock", "msgsnd", "msgrcv", "nsignals", "nvcsw", "nivcsw",
-      "stopped", "signaled","exited","success","coredump","exitstatus",
-      "termsig", "stopsig"
-    ]
-
-    @proc_stat_members = @proc_stat_members.map{ |e| e.to_sym }
-  end
-
-  test "version constant is set to expected value" do
-    assert_equal('1.8.1', Process::WAIT3_VERSION)
-    assert_true(Process::WAIT3_VERSION.frozen?)
-  end
-
-  test "wait3 method is defined" do
-    assert_respond_to(Process, :wait3)
-  end
-
-  test "wait3 works as expected" do
-    fork{ sleep 0.5 }
-    assert_nothing_raised{ Process.wait3 }
-  end
-
-  test "wait3 returns the expected proc status membes" do
-    fork{ sleep 0.5 }
-    assert_nothing_raised{ @proc_stat = Process.wait3 }
-    assert_equal(@proc_stat_members, @proc_stat.members)
-  end
-
-  test "wait3 with WNOHANG works as expected" do
-    fork{ sleep 0.5 }
-    assert_nothing_raised{ Process.wait3(Process::WNOHANG) }
-  end
-
-  test "wait3 sets and returns $last_status to expected values" do
-    fork{ sleep 0.5 }
-    Process.wait3
-    assert_kind_of(Struct::ProcStat, $last_status)
-    assert_not_nil($last_status)
-  end
-
-  test "wait3 sets pid and status members of $?" do
-    fork{ sleep 0.5 }
-    Process.wait3
-    assert_not_nil($?)
-  end
-
-  test "wait3 returns frozen struct" do
-    fork{ sleep 0.5 }
-    struct = Process.wait3
-    assert_true(struct.frozen?)
-  end
-
-  test "getdtablesize works as expected" do
-    omit_unless(@@solaris, 'getdtablesize skipped on this platform')
-
-    assert_respond_to(Process, :getdtablesize)
-    assert_kind_of(Fixnum, Process.getdtablesize)
-    assert(Process.getdtablesize > 0)
-  end
-
-  test "wait4 method is defined" do
-    omit_if(@@hpux, 'wait4 test skipped on this platform')
-    assert_respond_to(Process,:wait4)
-  end
-
-  test "wait4 requires at least one argument" do
-    assert_raises(ArgumentError){ Process.wait4 }
-  end
-
-  test "wait4 works as expected" do
-    omit_if(@@hpux, 'wait4 test skipped on this platform')
-
-    pid = fork{ sleep 0.5 }
-    assert_nothing_raised{ @proc_stat = Process.wait4(pid) }
-    assert_kind_of(Struct::ProcStat, @proc_stat)
-  end
-
-  test "wait4 sets and returns $last_status to expected values" do
-    pid = fork{ sleep 0.5 }
-    Process.wait4(pid)
-    assert_kind_of(Struct::ProcStat, $last_status)
-    assert_not_nil($last_status)
-  end
-
-  test "wait4 sets pid and status members of $?" do
-    pid = fork{ sleep 0.5 }
-    Process.wait4(pid)
-    assert_not_nil($?)
-  end
-
-  test "wait4 returns frozen struct" do
-    pid = fork{ sleep 0.5 }
-    struct = Process.wait4(pid)
-    assert_true(struct.frozen?)
-  end
-
-  test "waitid method is defined" do
-    omit_if(@@hpux || @@darwin || @@freebsd, 'waitid test skipped on this platform')
-    assert_respond_to(Process, :waitid)
-  end
-
-  test "waitid method works as expected" do
-    omit_if(@@hpux || @@darwin || @@freebsd, 'waitid test skipped on this platform')
-    pid = fork{ sleep 0.5 }
-    assert_nothing_raised{ Process.waitid(Process::P_PID, pid, Process::WEXITED) }
-  end
-
-  test "waitid method raises expected errors if wrong argument type is passed" do
-    omit_if(@@hpux || @@darwin || @@freebsd, 'waitid test skipped on this platform')
-    pid = fork{ sleep 0.5 }
-    assert_raises(TypeError){ Process.waitid("foo", pid, Process::WEXITED) }
-    assert_raises(TypeError){ Process.waitid(Process::P_PID, pid, "foo") }
-    assert_raises(TypeError){ Process.waitid(Process::P_PID, "foo", Process::WEXITED) }
-  end
-
-  test "waitid method raises expected error if invalid argument is passed" do
-    omit_if(@@hpux || @@darwin || @@freebsd, 'waitid test skipped on this platform')
-    fork{ sleep 0.5 }
-    assert_raises(Errno::ECHILD, Errno::EINVAL){ Process.waitid(Process::P_PID, 99999999, Process::WEXITED) }
-  end
-
-  test "sigsend method is defined" do
-    omit_unless(@@solaris, 'sigsend test skipped on this platform')
-    assert_respond_to(Process, :sigsend)
-  end
-
-  test "sigsend works as expected" do
-    omit_unless(@@solaris, 'sigsend test skipped on this platform')
-    pid = fork{ sleep 0.5 }
-    assert_nothing_raised{ Process.sigsend(Process::P_PID, pid, 0) }
-  end
-
-  test "getrusage method is defined" do
-    assert_respond_to(Process, :getrusage)
-  end
-
-  test "getrusage works as expected" do
-    fork{ sleep 0.5 }
-    assert_nothing_raised{ Process.getrusage }
-    assert_nothing_raised{ Process.getrusage(true) }
-  end
-
-  test "getrusage can get thread info on Linux" do
-    omit_unless(@@linux)
-    assert_nothing_raised{ Process.getrusage(Process::RUSAGE_THREAD) }
-  end
-
-  test "getrusage returns the expected struct" do
-    fork{ sleep 0.5 }
-    assert_kind_of(Struct::RUsage, Process.getrusage)
-    assert_kind_of(Float, Process.getrusage.stime)
-    assert_kind_of(Float, Process.getrusage.utime)
-  end
-
-  test "pause method is defined" do
-    assert_respond_to(Process, :pause)
-  end
-
-  test "expected constants are defined" do
-    omit_if(@@darwin || @@freebsd, 'wait constant check skipped on this platform')
-
-    assert_not_nil(Process::WCONTINUED)
-    assert_not_nil(Process::WEXITED)
-    assert_not_nil(Process::WNOWAIT)
-    assert_not_nil(Process::WSTOPPED)
-
-    omit_if(@@linux, 'WTRAPPED constant check skipped on this platform')
-    assert_not_nil(Process::WTRAPPED)
-  end
-
-  test "expected process type flag constants are defined" do
-    omit_if(@@linux || @@darwin || @@freebsd, 'process type flag check skipped on this platform')
-
-    assert_not_nil(Process::P_ALL)
-    assert_not_nil(Process::P_CID)
-    assert_not_nil(Process::P_GID)
-    assert_not_nil(Process::P_MYID) unless @@solaris
-    assert_not_nil(Process::P_PGID)
-    assert_not_nil(Process::P_PID)
-    assert_not_nil(Process::P_SID)
-    assert_not_nil(Process::P_UID)
-  end
-
-  test "solaris-specific process type flags are defined on solaris" do
-    omit_unless(@@solaris, 'P_TASKID and P_PROJID constant check skipped on this platform')
-
-    assert_not_nil(Process::P_TASKID)
-    assert_not_nil(Process::P_PROJID)
-  end
-
-  def teardown
-    @proc_stat = nil
-    @proc_stat_members = nil
-  end
-
-  def self.shutdown
-    @@solaris  = nil
-    @@darwin   = nil
-    @@hpux     = nil
-    @@linux    = nil
-    @@freebsd  = nil
-  end
-end