daemons 1.1.9 → 1.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e59f2e1546ffdb0c31f593a15204e5a027e64392
+  data.tar.gz: da329109adb90ff065d7ae0e7dd6b0238d83862d
+SHA512:
+  metadata.gz: 9e80ab5277dd3607978f6f5ccb23c95088f4dcaec7ecee4059a7649d071bc0c4451f6ece2f415c6900182a19b2e6abd5c8502b59876faa6cac66ec3eefee9eca
+  data.tar.gz: 0ce93e84a5ef74e07593193bcff94fec8d48687d0e9f976a2d289139ab7c74eb75c9e71811f696a5135eecc8836392ec56b95207982449ad8cd2ed8e19c89376

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2005-2012 Thomas Uehlinger
+Copyright (c) 2005-2015 Thomas Uehlinger, 2014-2015 Aaron Stone
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -0,0 +1,206 @@
+Ruby Daemons
+============
+
+Daemons provides an easy way to wrap existing ruby scripts (for example a self-written server)
+to be _run as a daemon_ and to be _controlled by simple start/stop/restart commands_.
+
+If you want, you can also use daemons to _run blocks of ruby code in a daemon process_ and to control
+these processes from the main application.
+
+Besides this basic functionality, daemons offers many advanced features like _exception backtracing_
+and logging (in case your ruby script crashes) and _monitoring_ and automatic restarting of your processes
+if they crash.
+
+Basic Usage
+-----------
+
+You can use Daemons in four different ways:
+
+### 1. Create wrapper scripts for your server scripts or applications
+
+Layout: suppose you have your self-written server `myserver.rb`:
+
+``` ruby
+# this is myserver.rb
+# it does nothing really useful at the moment
+
+loop do
+  sleep(5)
+end
+```
+
+To use `myserver.rb` in a production environment, you need to be able to
+run `myserver.rb` in the _background_ (this means detach it from the console, fork it
+in the background, release all directories and file descriptors).
+
+Just create `myserver_control.rb` like this:
+
+``` ruby
+# this is myserver_control.rb
+require 'daemons'
+
+Daemons.run('myserver.rb')
+```
+
+And use it like this from the console:
+
+``` ruby
+$ ruby myserver_control.rb start
+    (myserver.rb is now running in the background)
+$ ruby myserver_control.rb restart
+    (...)
+$ ruby myserver_control.rb stop
+```
+
+For testing purposes you can even run `myserver.rb` _without forking_ in the background:
+
+``` ruby
+$ ruby myserver_control.rb run
+```
+
+An additional nice feature of Daemons is that you can pass _additional arguments_ to the script that
+should be daemonized by seperating them by two _hyphens_:
+
+``` ruby
+$ ruby myserver_control.rb start -- --file=anyfile --a_switch another_argument
+```
+
+
+### 2. Create wrapper scripts that include your server procs
+
+Layout: suppose you have some code you want to run in the background and control that background process
+from a script:
+
+``` ruby
+# this is your code
+# it does nothing really useful at the moment
+
+loop do
+  sleep(5)
+end
+```
+
+To run this code as a daemon create `myproc_control.rb` like this and include your code:
+
+``` ruby
+# this is myproc_control.rb
+require 'daemons'
+
+Daemons.run_proc('myproc.rb') do
+  loop do
+    sleep(5)
+  end
+end
+```
+
+And use it like this from the console:
+
+``` ruby
+$ ruby myproc_control.rb start
+    (myproc.rb is now running in the background)
+$ ruby myproc_control.rb restart
+    (...)
+$ ruby myproc_control.rb stop
+```
+
+For testing purposes you can even run `myproc.rb` _without forking_ in the background:
+
+``` ruby
+$ ruby myproc_control.rb run
+```
+
+### 3. Control a bunch of daemons from another application
+
+Layout: you have an application `my_app.rb` that wants to run a bunch of
+server tasks as daemon processes.
+
+``` ruby
+# this is my_app.rb
+require 'daemons'
+
+task1 = Daemons.call(:multiple => true) do
+  # first server task
+
+  loop do
+    conn = accept_conn()
+    serve(conn)
+  end
+end
+
+task2 = Daemons.call do
+  # second server task
+
+  loop do
+    something_different()
+  end
+end
+
+# the parent process continues to run
+
+# we can even control our tasks, for example stop them
+task1.stop
+task2.stop
+
+exit
+```
+
+### 4. Daemonize the currently running process
+
+Layout: you have an application `my_daemon.rb` that wants to run as a daemon
+(but without the ability to be controlled by daemons via start/stop commands)
+
+``` ruby
+# this is my_daemons.rb
+require 'daemons'
+
+# Initialize the app while we're not a daemon
+init()
+
+# Become a daemon
+Daemons.daemonize
+
+# The server loop
+loop do
+  conn = accept_conn()
+  serve(conn)
+end
+```
+
+For further documentation, refer to the module documentation of Daemons.
+
+Displaying daemon status
+------------------------
+
+When daemonizing a process using a wrapper script, as examples 1 and 2 above,
+the status can be shown using
+
+``` ruby
+$ ruby myproc_control.rb status
+```
+
+By default this will display whether or not the daemon is running and, if it
+is, its PID.
+
+A custom message can be shown with
+
+``` ruby
+def custom_show_status(app)
+  # Display the default status information
+  app.default_show_status
+
+  puts
+  puts "PS information"
+  system("ps -p #{app.pid.pid.to_s}")
+
+  puts
+  puts "Size of log files"
+  system("du -hs /path/to/logs")
+end
+
+Daemons.run('myserver.rb', { show_status_callback: :custom_show_status })
+```
+
+Author
+------
+
+Written 2005-2015 by Thomas Uehlinger <thomas.uehlinger@gmail.com>, 2014-2015 by Aaron Stone <aaron@serendipity.cx>.

data/Releases

@@ -1,5 +1,22 @@
 = Daemons Release History
 
+== Release 1.2.1: March 10, 2015
+
+* increase version number to be able to re-push to rubygems
+
+== Release 1.2.0: March 8, 2015
+
+* add options for custum log file names.
+* change pid file name scheme to "#progname_num#{number}.pid" for multiple instances.
+* fix call_as_daemon not saving the PID (thanks Roberto Plancarte)
+* allow for custom statis messages (thanks to Joseph Haig)
+* fix Pid.running? rescuing timeout exceptions (thanks to Geraud Boyer)
+* monitor.rb/application.rb/application_group.rb: handle :monitor and :multiple in combination correctly
+  (thanks to Prakash Murthy).
+* pidfile.rb: Handle invalid or empty pid files instead of returning pid 0 (thanks to Aaron Stone)
+* run the whole gem through Rubocop (thanks to Aaron Stone)
+* gem cleanup (thanks to Aaron Stone)
+
 == Release 1.1.9: August 10, 2012
 
 * daemonize.rb: do srand in the forked child process both in daemonize and call_as_daemon 

data/examples/call/call.rb

@@ -6,12 +6,10 @@ else
   begin; require 'rubygems'; rescue ::Exception; end
 end
 
-
 require 'daemons'
 
 testfile = File.expand_path(__FILE__) + '.log'
 
-
 # On the first call to <tt<call</tt>, an application group (accessible by <tt>Daemons.group</tt>)
 # will be created an the options will be kept within, so you only have to specify
 # <tt>:multiple</tt> once.
@@ -23,35 +21,34 @@ options = {
   :multiple => true
 }
 
-
 Daemons.call(options) do
-  File.open(testfile, 'w') {|f|
-    f.puts "test"
-  }
+  File.open(testfile, 'w') do |f|
+    f.puts 'test'
+  end
 
-  loop { puts "1"; sleep 5 }
+  loop { puts '1'; sleep 5 }
 end
-puts "first task started"
+puts 'first task started'
 
 Daemons.call do
-  loop { puts "2"; sleep 4 }
+  loop { puts '2'; sleep 4 }
 end
-puts "second task started"
+puts 'second task started'
 
 # NOTE: this process will exit after 5 seconds
 Daemons.call do
-  puts "3"
+  puts '3'
   sleep 5
 end
-puts "third task started"
+puts 'third task started'
 
-puts "waiting 20 seconds..."
+puts 'waiting 20 seconds...'
 sleep(20)
 
-# This call would result in an exception as it will try to kill the third process 
+# This call would result in an exception as it will try to kill the third process
 # which has already terminated by that time; but using the 'true' parameter forces the
 # stop_all procedure.
-puts "trying to stop all tasks..."
+puts 'trying to stop all tasks...'
 Daemons.group.stop_all(true)
 
-puts "done"
+puts 'done'

data/examples/call/call_monitor.rb

@@ -6,12 +6,10 @@ else
   begin; require 'rubygems'; rescue ::Exception; end
 end
 
-
 require 'daemons'
 
 testfile = File.expand_path(__FILE__) + '.log'
 
-
 # On the first call to <tt<call</tt>, an application group (accessible by <tt>Daemons.group</tt>)
 # will be created an the options will be kept within, so you only have to specify
 # <tt>:multiple</tt> once.
@@ -23,33 +21,31 @@ options = {
   :monitor => true
 }
 
-
 Daemons.call(options) do
-  loop { puts "1"; sleep 20 }
+  loop { puts '1'; sleep 20 }
 end
-puts "first task started"
-
+puts 'first task started'
 
 # NOTE: this process will exit after 5 seconds
 Daemons.call do
-  File.open(testfile, 'a') {|f|
-    f.puts "started..."
-    puts "2"
-  
+  File.open(testfile, 'a') do |f|
+    f.puts 'started...'
+    puts '2'
+
     sleep 5
 
-    f.puts "...exit"
-  }
+    f.puts '...exit'
+  end
 end
-puts "second task started"
+puts 'second task started'
 
-puts "waiting 100 seconds..."
+puts 'waiting 100 seconds...'
 sleep(100)
 
-# This call would result in an exception as it will try to kill the third process 
+# This call would result in an exception as it will try to kill the third process
 # which has already terminated by that time; but using the 'true' parameter forces the
 # stop_all procedure.
-puts "trying to stop all tasks..."
+puts 'trying to stop all tasks...'
 Daemons.group.stop_all(true)
 
-puts "done"
+puts 'done'

data/examples/daemonize/daemonize.rb

@@ -6,22 +6,18 @@ else
   begin; require 'rubygems'; rescue ::Exception; end
 end
 
-
-
 require 'daemons'
 
-
 options = {
   :log_output => true
 }
 
-
 testfile = File.expand_path(__FILE__) + '.txt'
 
 Daemons.daemonize(options)
 
-puts "some output..."
+puts 'some output...'
 
-File.open(testfile, 'w') {|f|
-  f.write("test")
-}
+File.open(testfile, 'w') do |f|
+  f.write('test')
+end

data/examples/run/ctrl_crash.rb

@@ -8,7 +8,6 @@ end
 
 require 'daemons'
 
-
 options = {
   :log_output => true,
   :backtrace => true

data/examples/run/ctrl_custom_logfiles.rb

@@ -0,0 +1,18 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../lib'))
+
+if File.exist?(File.join(lib_dir, 'daemons.rb'))
+  $LOAD_PATH.unshift lib_dir
+else
+  begin; require 'rubygems'; rescue ::Exception; end
+end
+
+require 'daemons'
+
+options = {
+  :log_output => true,
+  :backtrace => true,
+  :output_logfilename => "custom_output.txt",
+  :logfilename => "custom_log.log"
+}
+
+Daemons.run(File.join(File.dirname(__FILE__), 'myserver_crashing.rb'), options)

data/examples/run/ctrl_exec.rb

@@ -8,7 +8,6 @@ end
 
 require 'daemons'
 
-
 options = {
   :mode => :exec
 }

data/examples/run/ctrl_exit.rb

@@ -8,7 +8,6 @@ end
 
 require 'daemons'
 
-
 options = {
 }
 

data/examples/run/ctrl_keep_pid_files.rb

@@ -8,10 +8,8 @@ end
 
 require 'daemons'
 
-
 options = {
   :keep_pid_files => true
 }
 
-
-Daemons.run(File.join(File.dirname(__FILE__), 'myserver.rb'), options)
+Daemons.run(File.join(File.dirname(__FILE__), 'myserver.rb'), options)