tornado.process
— Utilities for multiple processes¶
Utilities for working with multiple processes, including both forking the server into multiple processes and managing subprocesses.
-
exception
tornado.process.
CalledProcessError
[source]¶ An alias for
subprocess.CalledProcessError
.
-
tornado.process.
fork_processes
(num_processes: Optional[int], max_restarts: Optional[int] = None) → int[source]¶ Starts multiple worker processes.
If
num_processes
is None or <= 0, we detect the number of cores available on this machine and fork that number of child processes. Ifnum_processes
is given and > 0, we fork that specific number of sub-processes.Since we use processes and not threads, there is no shared memory between any server code.
Note that multiple processes are not compatible with the autoreload module (or the
autoreload=True
option totornado.web.Application
which defaults to True whendebug=True
). When using multiple processes, no IOLoops can be created or referenced until after the call tofork_processes
.In each child process,
fork_processes
returns its task id, a number between 0 andnum_processes
. Processes that exit abnormally (due to a signal or non-zero exit status) are restarted with the same id (up tomax_restarts
times). In the parent process,fork_processes
callssys.exit(0)
after all child processes have exited normally.max_restarts defaults to 100.
Availability: Unix
-
tornado.process.
task_id
() → Optional[int][source]¶ Returns the current task id, if any.
Returns None if this process was not created by
fork_processes
.
-
class
tornado.process.
Subprocess
(*args, **kwargs)[source]¶ Wraps
subprocess.Popen
with IOStream support.The constructor is the same as
subprocess.Popen
with the following additions:stdin
,stdout
, andstderr
may have the valuetornado.process.Subprocess.STREAM
, which will make the corresponding attribute of the resulting Subprocess aPipeIOStream
. If this option is used, the caller is responsible for closing the streams when done with them.
The
Subprocess.STREAM
option and theset_exit_callback
andwait_for_exit
methods do not work on Windows. There is therefore no reason to use this class instead ofsubprocess.Popen
on that platform.Changed in version 5.0: The
io_loop
argument (deprecated since version 4.1) has been removed.-
set_exit_callback
(callback: Callable[[int], None]) → None[source]¶ Runs
callback
when this process exits.The callback takes one argument, the return code of the process.
This method uses a
SIGCHLD
handler, which is a global setting and may conflict if you have other libraries trying to handle the same signal. If you are using more than oneIOLoop
it may be necessary to callSubprocess.initialize
first to designate oneIOLoop
to run the signal handlers.In many cases a close callback on the stdout or stderr streams can be used as an alternative to an exit callback if the signal handler is causing a problem.
Availability: Unix
-
wait_for_exit
(raise_error: bool = True) → Future[int][source]¶ Returns a
Future
which resolves when the process exits.Usage:
ret = yield proc.wait_for_exit()
This is a coroutine-friendly alternative to
set_exit_callback
(and a replacement for the blockingsubprocess.Popen.wait
).By default, raises
subprocess.CalledProcessError
if the process has a non-zero exit status. Usewait_for_exit(raise_error=False)
to suppress this behavior and return the exit status without raising.New in version 4.2.
Availability: Unix
-
classmethod
initialize
() → None[source]¶ Initializes the
SIGCHLD
handler.The signal handler is run on an
IOLoop
to avoid locking issues. Note that theIOLoop
used for signal handling need not be the same one used by individual Subprocess objects (as long as theIOLoops
are each running in separate threads).Changed in version 5.0: The
io_loop
argument (deprecated since version 4.1) has been removed.Availability: Unix