diff --git a/docs/api.rst b/docs/api.rst index 961b8790..e1496d66 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -52,7 +52,12 @@ bootstrap implementation sent to every new slave context. mitogen.master -------------- -.. automodule:: mitogen.master +.. module:: mitogen.master + +This module implements functionality required by master processes, such as +starting new contexts via SSH. Its size is also restricted, since it must +be sent to any context that will be used to establish additional child +contexts. mitogen.fakessh diff --git a/docs/internals.rst b/docs/internals.rst index 5da4cce5..675732a5 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -79,9 +79,71 @@ ExternalContext Class mitogen.master -=============== +============== -.. autoclass:: mitogen.master.ProcessMonitor +.. class:: mitogen.master.ProcessMonitor + + Install a :py:data:`signal.SIGCHLD` handler that generates callbacks when a + specific child process has exitted. + + .. method:: add (pid, callback) + + Add a callback function to be notified of the exit status of a process. + + :param int pid: + Process ID to be notified of. + + :param callback: + Function invoked as `callback(status)`, where `status` is the raw + exit status of the child process. + + +Blocking I/O Functions +---------------------- + +These functions exist to support the blocking phase of setting up a new +context. They will eventually be replaced with asynchronous equivalents. + + +.. function:: mitogen.master.iter_read(fd, deadline=None) + + Return a generator that arranges for up to 4096-byte chunks to be read at a + time from the file descriptor `fd` until the generator is destroyed. + + :param fd: + File descriptor to read from. + + :param deadline: + If not ``None``, an absolute UNIX timestamp after which timeout should + occur. + + :raises mitogen.core.TimeoutError: + Attempt to read beyond deadline. + + :raises mitogen.core.StreamError: + Attempt to read past end of file. + + +.. function:: mitogen.master.write_all (fd, s, deadline=None) + + Arrange for all of bytestring `s` to be written to the file descriptor + `fd`. + + :param int fd: + File descriptor to write to. + + :param bytes s: + Bytestring to write to file descriptor. + + :param float deadline: + If not ``None``, an absolute UNIX timestamp after which timeout should + occur. + + :raises mitogen.core.TimeoutError: + Bytestring could not be written entirely before deadline was exceeded. + + :raises mitogen.core.StreamError: + File descriptor was disconnected before write could complete. Helper Functions @@ -98,6 +160,51 @@ Helper Functions ECONNRESET may be triggered by any read or write. -.. autofunction:: mitogen.master.create_child -.. autofunction:: mitogen.master.get_child_modules -.. autofunction:: mitogen.master.minimize_source +.. function:: mitogen.master.create_child (\*args) + + Create a child process whose stdin/stdout is connected to a socket, + returning `(pid, socket_obj)`. + + +.. function:: mitogen.master.tty_create_child (\*args) + + Return a file descriptor connected to the master end of a pseudo-terminal, + whose slave end is connected to stdin/stdout/stderr of a new child process. + The child is created such that the pseudo-terminal becomes its controlling + TTY, ensuring access to /dev/tty returns a new file descriptor open on the + slave end. + + :param list args: + :py:func:`os.execl` argument list. + + :returns: + `(pid, fd)` + + +.. function:: mitogen.master.get_child_modules (path, fullname) + + Return the canonical names of all submodules of a package `module`. + + :param str path: + Path to the module's source code on disk, or some PEP-302-recognized + equivalent. Usually this is the module's ``__file__`` attribute, but + is specified explicitly to avoid loading the module. + + :param str fullname: + The module's canonical name. This is the module's ``__name__`` + attribute, but is specified explicitly to avoid loading the module. + + :return: + List of canonical submodule names. + + +.. autofunction:: mitogen.master.minimize_source (source) + + Remove comments and docstrings from Python `source`, preserving line + numbers and syntax of empty blocks. + + :param str source: + The source to minimize. + + :returns str: + The minimized source. diff --git a/mitogen/master.py b/mitogen/master.py index f80047df..1b7b25d7 100644 --- a/mitogen/master.py +++ b/mitogen/master.py @@ -1,9 +1,3 @@ -""" -This module implements functionality required by master processes, such as -starting new contexts via SSH. Its size is also restricted, since it must be -sent to any context that will be used to establish additional child contexts. -""" - import commands import errno import getpass @@ -43,8 +37,6 @@ IOLOG_RE = re.compile(r'^[ ]*IOLOG.debug\(.+?\)$', re.M) def minimize_source(source): - """Remove comments and docstrings from Python `source`, preserving line - numbers and syntax of empty blocks.""" subber = lambda match: '""' + ('\n' * match.group(0).count('\n')) source = DOCSTRING_RE.sub(subber, source) source = COMMENT_RE.sub('', source) @@ -52,7 +44,6 @@ def minimize_source(source): def get_child_modules(path, fullname): - """Return the canonical names of all submodules of a package `module`.""" it = pkgutil.iter_modules([os.path.dirname(path)]) return ['%s.%s' % (fullname, name) for _, name, _ in it] @@ -67,8 +58,6 @@ def format_cmdline(args): def create_child(*args): - """Create a child process whose stdin/stdout is connected to a socket, - returning `(pid, socket_obj)`.""" parentfp, childfp = socket.socketpair() pid = os.fork() if not pid: @@ -126,16 +115,6 @@ def close_nonstandard_fds(): def tty_create_child(*args): - """ - Return a file descriptor connected to the master end of a pseudo-terminal, - whose slave end is connected to stdin/stdout/stderr of a new child process. - The child is created such that the pseudo-terminal becomes its controlling - TTY, ensuring access to /dev/tty returns a new file descriptor open on the - slave end. - - :param args: - execl() arguments. - """ master_fd, slave_fd = os.openpty() disable_echo(master_fd) disable_echo(slave_fd)