[Zope3-checkins] SVN: zdaemon/trunk/ Added reference documentation
and some edge-case tests.
Jim Fulton
jim at zope.com
Mon Jan 8 06:59:15 EST 2007
Log message for revision 71789:
Added reference documentation and some edge-case tests.
Refined code in the control (user-interface) progream to detect
sooner if the deamon manager has exited.
Updated release info.
Changed:
U zdaemon/trunk/CHANGES.txt
U zdaemon/trunk/README.txt
U zdaemon/trunk/setup.py
U zdaemon/trunk/src/zdaemon/README.txt
U zdaemon/trunk/src/zdaemon/tests/tests.py
U zdaemon/trunk/src/zdaemon/zdctl.py
-=-
Modified: zdaemon/trunk/CHANGES.txt
===================================================================
--- zdaemon/trunk/CHANGES.txt 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/CHANGES.txt 2007-01-08 11:59:13 UTC (rev 71789)
@@ -4,12 +4,6 @@
To-Dos
======
-Tests:
-
-- non-daemon mode
-
-- no infinite loop when program fails on start
-
More docs:
- Document/demonstrate some important features, such as:
@@ -18,9 +12,6 @@
- working directory
-- Reference docs
-
-
Features
- environment variables
Modified: zdaemon/trunk/README.txt
===================================================================
--- zdaemon/trunk/README.txt 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/README.txt 2007-01-08 11:59:13 UTC (rev 71789)
@@ -1,8 +1,9 @@
-``zdaemon`` process controller
-==============================
+****************************************************
+``zdaemon`` process controller for Unix-ased systems
+****************************************************
Overview
---------
+********
'zdaemon' is a Python package which provides APIs for managing spplications
run as daemons. Its principal use to date has been to manage the application
Modified: zdaemon/trunk/setup.py
===================================================================
--- zdaemon/trunk/setup.py 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/setup.py 2007-01-08 11:59:13 UTC (rev 71789)
@@ -16,8 +16,7 @@
entry_points = """
[console_scripts]
-zdctl = zdaemon.zdctl:main
-zdrun = zdaemon.zdrun:main
+zdaemon = zdaemon.zdctl:main
"""
def read(*rnames):
@@ -29,6 +28,8 @@
zip_safe=False,
entry_points=entry_points,
include_package_data = True,
+ install_requires=["ZConfig"],
+ tests_require=["zope.testing"],
)
except ImportError:
from distutils.core import setup
@@ -37,10 +38,11 @@
name = "zdaemon"
setup(
name=name,
- version="1.4a2",
+ version="2.0a1",
url="http://www.python.org/pypi/zdaemon",
license="ZPL 2.1",
- description="Daemon process control library and tools",
+ description=
+ "Daemon process control library and tools for Unix-bases systems",
author="Zope Corporation and Contributors",
author_email="zope3-dev at zope.org",
long_description=(
@@ -48,13 +50,16 @@
+ '\n' +
read('CHANGES.txt')
+ '\n' +
+ 'Detailed Documentation\n'
+ '**********************\n'
+ + '\n' +
+ read('src', 'zdaemon', 'README.txt')
+ + '\n' +
'Download\n'
'**********************\n'
),
packages=["zdaemon", "zdaemon.tests"],
package_dir={"": "src"},
- install_requires=["ZConfig"],
- tests_require=["zope.testing"],
**setuptools_options)
Modified: zdaemon/trunk/src/zdaemon/README.txt
===================================================================
--- zdaemon/trunk/src/zdaemon/README.txt 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/src/zdaemon/README.txt 2007-01-08 11:59:13 UTC (rev 71789)
@@ -137,3 +137,192 @@
>>> system("./zdaemon -Cconf stop")
daemon process stopped
+Reference Documentation
+-----------------------
+
+The following options are available for use in the runner section of
+configuration files and as command-line options.
+
+program
+ Command-line option: -p or --program
+
+ This option gives the command used to start the subprocess
+ managed by zdaemon. This is currently a simple list of
+ whitespace-delimited words. The first word is the program
+ file, subsequent words are its command line arguments. If the
+ program file contains no slashes, it is searched using $PATH.
+ (Note that there is no way to to include whitespace in the program
+ file or an argument, and under certain circumstances other
+ shell metacharacters are also a problem.)
+
+socket-name
+ Command-line option: -s or --socket-name.
+
+ The pathname of the Unix domain socket used for communication
+ between the zdaemon command-line tool and a deamon-management
+ process. The default is relative to the current directory in
+ which zdaemon is started. You want to specify
+ an absolute pathname here.
+
+ This defaults to "zdsock", which is created in the directory
+ in which zdrun is started.
+
+daemon
+ Command-line option: -d or --daemon.
+
+ If this option is true, zdaemon runs in the background as a
+ true daemon. It forks a child process which becomes the
+ subprocess manager, while the parent exits (making the shell
+ that started it believe it is done). The child process also
+ does the following:
+
+ - if the directory option is set, change into that directory
+
+ - redirect stdin, stdout and stderr to /dev/null
+
+ - call setsid() so it becomes a session leader
+
+ - call umask() with specified value
+
+ The default for this option is on by default. The
+ command-line option therefore has no effect. To disable
+ daemon mode, you must use a configuration file::
+
+ <runner>
+ program sleep 1
+ daemon off
+ </runner>
+
+directory
+ Command-line option: -z or --directory.
+
+ If the daemon option is true (default), this option can
+ specify a directory into which zdrun.py changes as part of the
+ "daemonizing". If the daemon option is false, this option is
+ ignored.
+
+backoff-limit
+ Command-line option: -b or --backoff-limit.
+
+ When the subprocess crashes, zdaemon inserts a one-second
+ delay before it restarts it. When the subprocess crashes
+ again right away, the delay is incremented by one second, and
+ so on. What happens when the delay has reached the value of
+ backoff-limit (in seconds), depends on the value of the
+ forever option. If forever is false, zdaemon gives up at
+ this point, and exits. An always-crashing subprocess will
+ have been restarted exactly backoff-limit times in this case.
+ If forever is true, zdaemon continues to attempt to restart
+ the process, keeping the delay at backoff-limit seconds.
+
+ If the subprocess stays up for more than backoff-limit
+ seconds, the delay is reset to 1 second.
+
+ This defaults to 10.
+
+forever
+ Command-line option: -f or --forever.
+
+ If this option is true, zdaemon will keep restarting a
+ crashing subprocess forever. If it is false, it will give up
+ after backoff-limit crashes in a row. See the description of
+ backoff-limit for details.
+
+ This is disabled by default.
+
+exit-codes
+ Command-line option: -x or --exit-codes.
+
+ This defaults to 0,2.
+
+ If the subprocess exits with an exit status that is equal to
+ one of the integers in this list, zdaemon will not restart
+ it. The default list requires some explanation. Exit status
+ 0 is considered a willful successful exit; the ZEO and Zope
+ server processes use this exit status when they want to stop
+ without being restarted. (Including in response to a
+ SIGTERM.) Exit status 2 is typically issued for command line
+ syntax errors; in this case, restarting the program will not
+ help!
+
+ NOTE: this mechanism overrides the backoff-limit and forever
+ options; i.e. even if forever is true, a subprocess exit
+ status code in this list makes zdaemon give up. To disable
+ this, change the value to an empty list.
+
+user
+ Command-line option: -u or --user.
+
+ When zdaemon is started by root, this option specifies the
+ user as who the the zdaemon process (and hence the daemon
+ subprocess) will run. This can be a user name or a numeric
+ user id. Both the user and the group are set from the
+ corresponding password entry, using setuid() and setgid().
+ This is done before zdaemon does anything else besides
+ parsing its command line arguments.
+
+ NOTE: when zdaemon is not started by root, specifying this
+ option is an error. (XXX This may be a mistake.)
+
+ XXX The zdaemon event log file may be opened *before*
+ setuid() is called. Is this good or bad?
+
+umask
+ Command-line option: -m or --umask.
+
+ When daemon mode is used, this option specifies the octal umask
+ of the subprocess.
+
+default-to-interactive
+ If this option is true, zdaemon enters interactive mode
+ when it is invoked without a positional command argument. If
+ it is false, you must use the -i or --interactive command line
+ option to zdaemon to enter interactive mode.
+
+ This is enabled by default.
+
+logfile
+ This option specifies a log file that is the default target of
+ the "logtail" zdaemon command.
+
+ NOTE: This is NOT the log file to which zdaemon writes its
+ logging messages! That log file is specified by the
+ <eventlog> section described below.
+
+transcript
+ The name of a file in which a transcript of all output from
+ the command being run will be written to when daemonized.
+
+ If not specified, output from the command will be discarded.
+
+ This only takes effect when the "daemon" option is enabled.
+
+prompt
+ The prompt shown by the controller program. The default must
+ be provided by the application.
+
+(Note that a few other options are available to support old
+configuration files, but aren't needed any more and can generally be
+ignored.)
+
+In addition to the runner section, you can use an eventlog section
+that specified one or more logfile subsections::
+
+ <eventlog>
+ <logfile>
+ path /var/log/foo/foo.log
+ </logfile>
+
+ <logfile>
+ path STDOUT
+ </logfile>
+ </eventlog>
+
+In this example, log output is sent to a file and to standard out.
+Log output from zdaemon usually isn't very interesting but can be
+handy for debugging.
+
+
+
+
+
Modified: zdaemon/trunk/src/zdaemon/tests/tests.py
===================================================================
--- zdaemon/trunk/src/zdaemon/tests/tests.py 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/src/zdaemon/tests/tests.py 2007-01-08 11:59:13 UTC (rev 71789)
@@ -31,6 +31,44 @@
zconfig_loc = pkg_resources.working_set.find(
pkg_resources.Requirement.parse('ZConfig')).location
+
+def make_sure_non_daemon_mode_doesnt_hang_when_program_exits():
+ """
+ The whole awhile bit that waits for a program to start
+ whouldn't be used on non-daemopn mode.
+
+ >>> open('conf', 'w').write(
+ ... '''
+ ... <runner>
+ ... program sleep 1
+ ... daemon off
+ ... </runner>
+ ... ''')
+
+ >>> system("./zdaemon -Cconf start")
+
+ """
+
+def dont_hang_when_program_doesnt_start():
+ """
+ If a program doesn't start, we don't want to wait for ever.
+
+ >>> open('conf', 'w').write(
+ ... '''
+ ... <runner>
+ ... program sleep
+ ... backoff-limit 2
+ ... </runner>
+ ... ''')
+
+ >>> system("./zdaemon -Cconf start")
+ . .
+ Daemon manager not running.
+
+ """
+
+
+
def setUp(test):
test.globs['_td'] = td = []
here = os.getcwd()
@@ -60,8 +98,15 @@
print o.read(),
+
def test_suite():
return unittest.TestSuite((
+ doctest.DocTestSuite(
+ setUp=setUp, tearDown=tearDown,
+ checker=renormalizing.RENormalizing([
+ (re.compile('pid=\d+'), 'pid=NNN'),
+ ])
+ ),
doctest.DocFileSuite(
'../README.txt',
setUp=setUp, tearDown=tearDown,
Modified: zdaemon/trunk/src/zdaemon/zdctl.py
===================================================================
--- zdaemon/trunk/src/zdaemon/zdctl.py 2007-01-08 00:10:56 UTC (rev 71788)
+++ zdaemon/trunk/src/zdaemon/zdctl.py 2007-01-08 11:59:13 UTC (rev 71789)
@@ -177,16 +177,22 @@
def awhile(self, cond, msg):
n = 0
+ was_running = True
try:
- self.get_status()
+ if self.get_status():
+ was_running = True
+
while not cond():
sys.stdout.write(". ")
sys.stdout.flush()
time.sleep(1)
n += 1
- if not self.get_status() and n > 10:
+ if self.get_status():
+ was_running = True
+ elif was_running or n > 10:
print "\nDaemon manager not running."
return
+
except KeyboardInterrupt:
print "^C"
else:
More information about the Zope3-Checkins
mailing list