Document PidFileBase constructor arguments

[rudolfbyker]

I can't find any documentation for the PidFileBase constructor's arguments. I've been reading the source code, and I'm having trouble seeing e.g. what the difference between lock_pidfile and allow_samepid is.

[trbs]

Your right in that documentation is poor / non-existent :-(

Also I've been thinking for a while that the constructor argument probably should be reshuffled to make more intuitive sense...

The tests might also help deciphering things a bit, although that's also not like proper documentation.

From the top of my head:

• lock_pidfile using a filesystem lock to detect an existing-in-use pidfile, avoid race condition, etc.
• allow_samepid makes a single process with multiple instances re-entrant.

The interplay is that one can have:

• lock_pidfile=False, allow_samepid=True; PidFile is re-entrant, multiple PidFile instances inside the same process will work and no filesystem level lock is taken. (eg: your filesystem does not support locks or you just don't want them :D)
• lock_pidfile=False, allow_samepid=False; error is raised PidFile is not re-entrant.
• lock_pidfile=True, allow_samepid=True; PidFile is re-entrant, multiple PidFile instances inside the same process will work and a filesystem level lock is taken on the pidfile.
• lock_pidfile=True, allow_samepid=False; [default] PidFile is not re-entrant; a second PidFile instance inside the same process will raise an exception and a filesystem level lock is taken on the pidfile.