Phantom
This gem is made to implement the callback mechanism to sub processes.
Requirements
Ruby >= 2.0.0
This gem uses ::fork
and therefore is not compatible with JRuby.
Installation
Add this line to your application's Gemfile:
gem 'phantom'
And then execute:
$ bundle
Or install it yourself as:
$ gem install phantom
Usage
begin
phantom = Phantom.run(pid_file: '/path/to/your.pid',
on_ok: method(:my_ok_callback),
on_error: method(:my_error_callback)) do
# Do your background job here
end
rescue Phantom::ForkError => e
puts e.pid_file #=> pid file path
puts e. #=> error message
end
phantom.pid #=> PID or nil if fork fails
phantom.name #=> name of the subprocess. The name equals to the name displayed by linux command `ps`.
phantom.status #=> 'Alive' | 'Dead' | 'Paused'
phantom.dead? #=> true if the sub process is dead (i.e. either ended normally or killed)
phantom.alive? #=> true if not dead.
phantom.stop #=> pause the sub process
phantom.pause #=> pause is an alias of stop
phantom.continue #=> resume the sub process
phantom.resume #=> resume is an alias of continue
phantom.kill(1) #=> send signal to the sub process
phantom.kill(:TERM) #=> you can as well use the POSIX signal names
phantom.terminate #=> terminate the sub process gracefully
phantom.abort! #=> force the sub process to end immediately
The on_ok
parameter can be any instances that respond to call
taking no arguments.
The on_error
parameter can be any instances that respond to call
taking 1 argument, the exception.
None of the parameters is required.
If pid_file
is given, Phantom.run
first check the existence of the file, if exits, raises a Phantom::ForkError
.
If you want a global mutex (i.e. mutex between multiple processes), you can use the Phutex
instances.
@phutex = Phantom::Phutex.new('path/to/your/lock/file')
@phutex.sync do
# do your job here
end
Caution
- The status is NOT completely retrieved from the sub process, so any manipulation out of the phantom instance, except terminating the sub process, will not be recognized.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request