proc-wait3 1.8.1 → 1.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a183dbb97844a741719f7e1b6827d11f433c36995607078ea25face079e05255
-  data.tar.gz: b56692543a16b3334fc2b64a849007a0bb95755534e4b09b4c1851c123711080
+  metadata.gz: d2054430d4049b9aa27f1902f704220818bf4e6b8d7d19e428e10e3ed736d6c9
+  data.tar.gz: 9be23be7ddad009649f5ec83692102b05334a9013d99a68f1643c1c2eda37b62
 SHA512:
-  metadata.gz: 1ef23ac082d86b18c7c8c39396343f98a7d6f1e7f64299cdd5a4f9ed5f0341caeb857a99533d031f665df861b808288c15d7cde0ceb5c443ef8d1b47ed17cdd3
-  data.tar.gz: b7b32cf67ff465561213cc99446b1c34b048524a0babb276c42e9a8811e06210945bc7db4c2bb4f73e8c97b76559e6dc883d6dcc85adba9c19f8193c343e0706
+  metadata.gz: a6f95da3b81622fd0a4ca7be57f787ec63201be854f28bcb023aec9af3360ef8ec6af228ca3c180dfa7163831456aa57fd68ced837cb40d46f3b262e2a2b4554
+  data.tar.gz: fff3abd919e4c0f07ab666ea3f3a1db8d514fa63802fd408b57c87f0c8208d6cf4e886813605156625bc00e8b931405098e5a714d34a91a00830287974603507

data/{CHANGES.rdoc → CHANGES.md}

@@ -1,8 +1,18 @@
-== 1.8.1 - 8-Apr-2020
+## 1.9.1 - 8-Feb-2024
+* Replace sigset with sigaction in the pause method.
+* General cleanup and platform handling updates.
+
+## 1.9.0 - 7-Jan-2021
+* Switched from test-unit to rspec.
+* Skip some tests on Darwin because of EINTR errors.
+* Switched from rdoc to markdown since github isn't rendering rdoc properly.
+* Added a Gemfile.
+
+## 1.8.1 - 8-Apr-2020
 * Added a LICENSE file to the distribution as required by the Apache-2.0 license.
 * Add an explicit .rdoc extension to the README, CHANGES and MANIFEST files.
 
-== 1.8.0 - 20-Feb-2019
+## 1.8.0 - 20-Feb-2019
 * Changed license to Apache-2.0.
 * Now requires Ruby 2.2 or later.
 * Now checks for <bsd/string.h> header and include's it if found. This was
@@ -13,21 +23,21 @@
 * Removed some old macro checks/definitions that were no longer relevant.
 * Added a proc-wait3.rb file for convenience.
 
-== 1.7.3 - 21-Nov-2015
+## 1.7.3 - 21-Nov-2015
 * Fixed a bug where tv_usec was divided by 1k instead of 1e6. Thanks go to
   Jason Gladish for the spot.
 * This gem is now signed.
 * The gem related tasks in the Rakefile now assume Rubygems 2.x.
 
-== 1.7.2 - 5-Sep-2014
+## 1.7.2 - 5-Sep-2014
 * Added support for the RUSAGE_THREAD constant on Linux. Thanks go to
   Bruno Michel for the patch.
 
-== 1.7.1 - 24-Apr-2014
+## 1.7.1 - 24-Apr-2014
 * Explicitly check for and include sys/resource.h because Debian. Thanks
   go to Christos Trochalakis for the spot.
 
-== 1.7.0 - 6-Apr-2014
+## 1.7.0 - 6-Apr-2014
 * The wait3 and wait4 methods no longer set $? to a custom struct. The builtin
   variable is still set, but if you need the custom Struct::ProcStat information
   then use the $last_status global instead, or just use the return value. This
@@ -36,12 +46,12 @@
 * Some build warning fixes for BSD platforms.
 * Some test updates for BSD and Solaris.
 
-== 1.6.0 - 28-Aug-2011
+## 1.6.0 - 28-Aug-2011
 * Removed the getrlimit and setrlimit methods. Ruby has supported these methods
   since Ruby 1.8.5, so I think it's time to finally dump them.
 * Fixed two build warnings regarding unused variables and one 32/64 cast warning.
 
-== 1.5.6 - 7-Jan-2010
+## 1.5.6 - 7-Jan-2010
 * Checks are now made for the si_fd, si_utime, si_status and si_stime siginfo_t
   struct members. This addresses build failures on OS X 10.5 and later where
   those struct members went mysteriously MIA.
@@ -51,7 +61,7 @@
 * Updates to the README.
 * Source code moved to github.
 
-== 1.5.5 - 8-Aug-2009
+## 1.5.5 - 8-Aug-2009
 * Now compatible with Ruby 1.9.x.
 * License changed to Artistic 2.0.
 * Added test-unit 2.x as a development dependency.
@@ -62,7 +72,7 @@
 * Example files renamed to avoid any confusion with actual test files.
 * Several Rake tasks added to run individual example programs.
 
-== 1.5.4 - 7-Feb-2008
+## 1.5.4 - 7-Feb-2008
 * ALERT! ALERT! Now auto-patches your mkmf.rb file to add the 'have_const'
   method if it's not already found. This is necessary to determine if certain
   enum values exist on your system. Your original mkmf.rb is backed up first
@@ -73,7 +83,7 @@
 * Fixed the extconf.rb file so that it sets the target directory properly.
 * No source code changes (except for comment updates and a version bump).
 
-== 1.5.3 - 25-Oct-2006
+## 1.5.3 - 25-Oct-2006
 * Because not all platforms support automatically converting signal names
   into their equivalent numbers, the Process.pause method now accepts names
   or numbers.  It will raise an ArgumentError if you try to use a signal name
@@ -86,7 +96,7 @@
 * Internal fixes for platforms that don't support the strlcpy() function.
 * Minor update for the test_pause.rb example program.
 
-== 1.5.2 - 24-Jul-2006
+## 1.5.2 - 24-Jul-2006
 * Fixed the way I was handling whether or not Ruby already defined the various
   RLIMIT constants within wait3.c.
 * Fixed the way in which certain RLIM constants were being converted. I
@@ -95,7 +105,7 @@
 * Added the WAIT3_VERSION constant.
 * The getrlimit and setrlimit tests are now skipped for Ruby 1.8.5 or later.
 
-== 1.5.1 - 13-Jul-2006
+## 1.5.1 - 13-Jul-2006
 * Fixed bugs with improper values being set for some of the rlimit constants.
 * Cleaned up a few warnings related to signed-ness for the RLIM_xxx constants.
 * Now only sets the various rlimit constants if they're not already defined
@@ -103,21 +113,21 @@
 * Some internal cleanup.
 * Created a gemspec and added a gem to RubyForge.
 
-== 1.5.0 - 12-Jun-2006
+## 1.5.0 - 12-Jun-2006
 * Removed the '?' character from the various struct members, since Ruby
   no longer (properly) handles them.
 * Fixed a 64 bit bug related to rb_struct_define.
 * Added some more tests.
 
-== 1.4.3 - 28-Jun-2005
+## 1.4.3 - 28-Jun-2005
 * Added more #ifdef checks for some of the process flags which, it turns
   out, are not defined in earlier versions of Linux.
 
-== 1.4.2 - 14-Jun-2005
+## 1.4.2 - 14-Jun-2005
 * Fixed a syntax error that could cause the build to fail.
 * Removed some (but not all) possible warnings from gcc -Wall.
 
-== 1.4.1 - 13-Jun-2005
+## 1.4.1 - 13-Jun-2005
 * Added support for the Linux 2.6.9+ kernel (by adding more preprocessor
   constant checks, which may help with other platforms as well).
 * Moved project to RubyForge.
@@ -125,34 +135,34 @@
 * Removed the wait3.rd file.
 * Minor fix for the test_waitid.rb sample program.
 
-== 1.4.0 - 16-Feb-2005
+## 1.4.0 - 16-Feb-2005
 * Added the getrusage method.
 * Added test cases and documentation for getrusage.
 * Renamed a couple test files in the examples directory.
 
-== 1.3.0 - 14-Feb-2005
+## 1.3.0 - 14-Feb-2005
 * Added the pause and sigsend methods.
 * I had to modify the process type constants to include the "P_", because
   Ruby already has Process::GID and Process::UID defined.  That makes this
   release incompatible with previous versions.
 * Updated tests and documentation.
 
-== 1.2.0 - 7-Feb-2005
+## 1.2.0 - 7-Feb-2005
 * Added the Proc.waitid method (for those platforms that support it). 
 * Made the wait3.c file more rdoc friendly.
 * Added a test_waitid.rb file in the examples directory.
 
-== 1.1.1 - 10-Jan-2005
+## 1.1.1 - 10-Jan-2005
 * Eliminated some (harmless) warnings that cropped up in 1.8.2
 * Moved the "examples" directory to the toplevel directory.
 * Made docs slightly more rdoc friendly
 
-== 1.1.0 - 14-Sep-2004
+## 1.1.0 - 14-Sep-2004
 * Modified setup and source to handle the possibility that wait3() might
   be defined while wait4() is not (e.g. HPUX).
 * Modified the test scripts in the examples directory to play nice on HPUX
   and Darwin.
 * Added this file (oops).
 
-== 1.0.0 - 13-Sep-2004
+## 1.0.0 - 13-Sep-2004
 - Initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/{MANIFEST.rdoc → MANIFEST.md}

@@ -1,11 +1,12 @@
-* CHANGES.rdoc
+* CHANGES.md
+* Gemfile
 * LICENSE
-* MANIFEST.rdoc
+* MANIFEST.md
 * Rakefile
-* README.rdoc
+* README.md
 * proc-wait3.gemspec
 * certs/djberg96_pub.pem
-* doc/wait3.txt
+* doc/wait3.md
 * ext/extconf.rb
 * ext/proc/wait3.c
 * examples/example_getrusage.rb

data/{README.rdoc → README.md}

@@ -1,28 +1,32 @@
-= Description
+[![Ruby](https://github.com/djberg96/proc-wait3/actions/workflows/ruby.yml/badge.svg)](https://github.com/djberg96/proc-wait3/actions/workflows/ruby.yml)
+
+## Description
 Adds the wait3, wait4, waitid, pause, sigsend, and getrusage methods to the Process module.
 
-= Installation
-  gem install proc-wait3
+## Installation
+`gem install proc-wait3`
 
-= Synopsis
-  require 'proc/wait3'
+## Synopsis
+```ruby
+require 'proc/wait3'
 
-  pid = fork{
-    sleep 1
-    exit 2
-  }
+pid = fork{
+  sleep 1
+  exit 2
+}
 
-  puts Time.now.to_s
-  Process.wait3
-  puts $?.exitstatus # => 2
+puts Time.now.to_s
+Process.wait3
+puts $?.exitstatus # => 2
+```
 
-= Tested Platforms
-  * Solaris
-  * Linux
-  * FreeBSD
-  * OS X
+## Tested Platforms
+* Solaris
+* Linux
+* FreeBSD
+* OS X
 
-= Warnings
+## Warnings
 Linux users who compile with gcc -Wall will notice a few warnings. These
 are harmless (and unavoidable atm).
 
@@ -30,8 +34,11 @@ Linux users may also notice warnings about implicit declarations. These
 are also harmless, and can be silenced by installing the libbsd-dev package
 first.
 
-= Integration with Ruby's process.c
+These methods may fail in conjunction with `fork` with `Errno::EINTR` unless
+you pass the WNOHANG flag, or explicitly ignore the `SIGCHLD` signal. Ruby's
+own `wait` methods appear to essentially be doing that behind the scenes.
 
+## Integration with Ruby's process.c
 I considered simply providing a patch to the core process.c file, but I
 decided against it for two reasons.  First, I wanted to get something
 out more quickly rather than waiting for approval from the core developers
@@ -44,6 +51,5 @@ The overloaded methods are also overkill, and do nothing but save me the
 trouble of typing the word "status", since all they're for is comparing or
 operating on the status attribute.
 
-= Additional Documentation
-
-Please see the doc/wait3.txt file for detailed documentation.
+## Additional Documentation
+Please see the doc/wait3.md file for detailed documentation.

data/Rakefile

@@ -1,20 +1,22 @@
 require 'rake'
 require 'rake/clean'
-require 'rake/testtask'
+require 'rspec/core/rake_task'
 require 'fileutils'
 require 'rbconfig'
 include RbConfig
 
 CLEAN.include(
-  '**/*.gem',               # Gem files
-  '**/*.rbc',               # Rubinius
-  '**/*.o',                 # C object file
-  '**/*.log',               # Ruby extension build log
-  '**/Makefile',            # C Makefile
-  '**/conftest.dSYM',       # OS X build directory
-  "**/*.#{CONFIG['DLEXT']}" # C shared object
+  '**/*.gem',                # Gem files
+  '**/*.rbc',                # Rubinius
+  '**/*.o',                  # C object file
+  '**/*.log',                # Ruby extension build log
+  '**/Makefile',             # C Makefile
+  '**/conftest.dSYM',        # OS X build directory
+  "**/*.#{CONFIG['DLEXT']}", # C shared object
+  '**/*.lock'                # Bundler
 )
 
+
 desc "Build the source (but don't install it)"
 task :build => [:clean] do |t|
   Dir.chdir('ext') do
@@ -28,9 +30,9 @@ namespace :gem do
   desc "Create the proc-wait3 gem"
   task :create => [:clean] do
     require 'rubygems/package'
-    spec = eval(IO.read('proc-wait3.gemspec'))
+    spec = Gem::Specification.load('proc-wait3.gemspec')
     spec.signing_key = File.join(Dir.home, '.ssh', 'gem-private_key.pem')
-    Gem::Package.build(spec, true)
+    Gem::Package.build(spec)
   end
 
   desc "Install the proc-wait3 gem"
@@ -67,11 +69,9 @@ namespace :example do
   end
 end
 
-Rake::TestTask.new do |t|
-  task :test => [:build]
-  t.libs << 'ext'
-  t.warning = true
-  t.verbose = true
+desc "Run the test suite"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = '-Iext'
 end
 
-task :default => :test
+task :default => [:build, :spec]

data/doc/wait3.md

@@ -0,0 +1,225 @@
+## Description
+Adds the `wait3`, `wait4`, `waitid`, `pause`, `sigsend`, and `getrusage`
+methods to the Process module.
+
+## Synopsis
+```ruby
+require 'proc/wait3'
+
+pid = fork{ sleep 1; exit 2 }
+p Time.now
+Process.wait3
+p $?
+```
+
+## Module Methods
+### `Process.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 underlying `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.
+
+## Standard Constants
+`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.
+
+## Process type constants - not all platforms supported
+`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.
+
+## Additional Process constants - defined if waitid is defined 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.
+
+## Future Plans
+Wrap the wait6 function, and add better BSD support in general.
+
+## 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-2024 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/examples/example_pause.rb

@@ -11,7 +11,7 @@ require 'proc/wait3'
 
 puts "Pausing.  Hit Ctrl-C to continue."
 
-if Config::CONFIG['host_os'] =~ /linux/i
+if RbConfig::CONFIG['host_os'] =~ /linux|darwin/i
    Process.pause(2)
 else
    Process.pause("INT")

data/ext/extconf.rb

@@ -7,7 +7,7 @@ require 'mkmf'
 dir_config('proc-wait3')
 
 have_header('wait.h')
-have_header('sys/resource.h')
+have_header('sys/resource.h') # apt install libbsd-dev
 have_header('sys/wait.h')
 
 # wait3 is mandatory.
@@ -53,20 +53,7 @@ have_struct_member('struct siginfo', 'si_stime', 'signal.h')
 
 have_const('P_CID', 'signal.h')
 have_const('P_GID', 'signal.h')
-have_const('P_MYID', 'signal.hclass PasswdStruct < FFI::Struct
-      layout(
-        :pw_name, :string,
-        :pw_passwd, :string,
-        :pw_uid, :uint,
-        :pw_gid, :uint,
-        :pw_change, :ulong,
-        :pw_class, :string,
-        :pw_gecos, :string,
-        :pw_dir, :string,
-        :pw_shell, :string,
-        :pw_expire, :ulong
-      )
-    end')
+have_const('P_MYID', 'signal.h')
 have_const('P_SID', 'signal.h')
 have_const('P_UID', 'signal.h')