Contradictory Documentation/Example code

[paulwalker]

The documentation for watching a non-daemon process says:

WATCHING NON-DAEMON PROCESSES
Need to watch a script that doesn't have built in daemonization? No problem! 
God will daemonize and keep track of your process for you. 
If you don't specify a pid_file attribute for a watch, 
it will be auto-daemonized and a PID file will be stored for it in /var/run/god.

It says, "If you don't specify a pid_file attribute...

However, the two example that follow each have a comment that says the opposite:

God.pid_file_directory = '/home/tom/pids'

# Watcher that auto-daemonizes and creates the pid file
God.watch do |w|
  w.name = 'mongrel'
  w.pid_file = w.pid_file = File.join(RAILS_ROOT, "log/mongrel.pid")

  w.start = "mongrel_rails start -P #{RAILS_ROOT}/log/mongrel.pid  -d"

  # ...
end

# Watcher that does not auto-daemonize
God.watch do |w|
  w.name = 'worker'
  # w.pid_file = is not set

  w.start = "rake resque:worker"

  # ...
end

The first example specifies the pid_file and the comment above it says that God will auto-daemonize it. The second example does the opposite.

Which is correct, the example or the documentation?

[martron]

I just ran into this and trial and errored it. For version 0.7.18 NOT specifying the pid file made the script daemonize properly.

[eric]

It sounds like this has to do with a confusion in terminology.

Instead of saying "Watcher that auto-daemonizes" it should say "process that auto-daemonizes".

Same for the second one. "Watcher" should be replaced with "Process".

[paulwalker]

That's not my particular confusion. What is the intended behavior? It is intended that god will auto-daemonize when specifying a pid file or not specifying a pid file? The initial documentation says the latter but the code examples illustrate the former.

[eric]

The intended behavior is to support programs that daemonize themselves as well as ones that don't.

For processes that daemonize themselves, they need to provide the PID of the daemonized process so god knows to watch that process. The way that is communicated is by specifying a w.pid_file = which will point to the file that god should read to find the PID that it should monitor.

For processes that don't daemonize themselves, god will see that there is no w.pid_file = defined and will call fork() itself to daemonize the process and will write a pid file (so that if god is restarted, it knows what the PID of the daemon is).

In the case of mongrel_rails, that process knows how to daemonize itself, so a w.pid_file = is specified that points to where mongrel_rails will write the pid file.

In the case of rake, the process doesn't know how to daemonize itself, so no w.pid_file = is specified and god will daemonize and create a pid file for it.

[paulwalker]

Ah, now I understand. Yes, I would change the sentence subject from "watcher" to "process" as you suggested. Additionally, I would add text to make it clear that GOD in the second example will daemonize the process for you and the location of the consequent pid file (/var/run/god/worker.pid?).

A big part of my confusion is that I assumed setting the pid_file for the watcher was telling god where to put the pid file...not that I was setting where the process that already daemonizes puts the pid file.

Maybe naming the setting "process_pid_file" would have helped me. Is there no way to tell god where to store pid files that it creates?