[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