diff --git a/lib/spack/llnl/util/tty/pty.py b/lib/spack/llnl/util/tty/pty.py
index ef5d40ea57c1fcd1b729f4adc35cc7fb36a6f50d..84c272a6e23538597ded2b3c0f9a6ca8a83561ee 100644
--- a/lib/spack/llnl/util/tty/pty.py
+++ b/lib/spack/llnl/util/tty/pty.py
@@ -31,17 +31,17 @@
class ProcessController(object):
"""Wrapper around some fundamental process control operations.
- This allows one process to drive another similar to the way a shell
- would, by sending signals and I/O.
+ This allows one process (the controller) to drive another (the
+ minion) similar to the way a shell would, by sending signals and I/O.
"""
- def __init__(self, pid, master_fd,
+ def __init__(self, pid, controller_fd,
timeout=1, sleep_time=1e-1, debug=False):
"""Create a controller to manipulate the process with id ``pid``
Args:
pid (int): id of process to control
- master_fd (int): master file descriptor attached to pid's stdin
+ controller_fd (int): controller fd attached to pid's stdin
timeout (int): time in seconds for wait operations to time out
(default 1 second)
sleep_time (int): time to sleep after signals, to control the
@@ -58,7 +58,7 @@ def __init__(self, pid, master_fd,
"""
self.pid = pid
self.pgid = os.getpgid(pid)
- self.master_fd = master_fd
+ self.controller_fd = controller_fd
self.timeout = timeout
self.sleep_time = sleep_time
self.debug = debug
@@ -67,8 +67,8 @@ def __init__(self, pid, master_fd,
self.ps = which("ps", required=True)
def get_canon_echo_attrs(self):
- """Get echo and canon attributes of the terminal of master_fd."""
- cfg = termios.tcgetattr(self.master_fd)
+ """Get echo and canon attributes of the terminal of controller_fd."""
+ cfg = termios.tcgetattr(self.controller_fd)
return (
bool(cfg[3] & termios.ICANON),
bool(cfg[3] & termios.ECHO),
@@ -82,7 +82,7 @@ def horizontal_line(self, name):
)
def status(self):
- """Print debug message with status info for the child."""
+ """Print debug message with status info for the minion."""
if self.debug:
canon, echo = self.get_canon_echo_attrs()
sys.stderr.write("canon: %s, echo: %s\n" % (
@@ -94,12 +94,12 @@ def status(self):
sys.stderr.write("\n")
def input_on(self):
- """True if keyboard input is enabled on the master_fd pty."""
+ """True if keyboard input is enabled on the controller_fd pty."""
return self.get_canon_echo_attrs() == (False, False)
def background(self):
- """True if pgid is in a background pgroup of master_fd's terminal."""
- return self.pgid != os.tcgetpgrp(self.master_fd)
+ """True if pgid is in a background pgroup of controller_fd's tty."""
+ return self.pgid != os.tcgetpgrp(self.controller_fd)
def tstp(self):
"""Send SIGTSTP to the controlled process."""
@@ -115,18 +115,18 @@ def cont(self):
def fg(self):
self.horizontal_line("fg")
with log.ignore_signal(signal.SIGTTOU):
- os.tcsetpgrp(self.master_fd, os.getpgid(self.pid))
+ os.tcsetpgrp(self.controller_fd, os.getpgid(self.pid))
time.sleep(self.sleep_time)
def bg(self):
self.horizontal_line("bg")
with log.ignore_signal(signal.SIGTTOU):
- os.tcsetpgrp(self.master_fd, os.getpgrp())
+ os.tcsetpgrp(self.controller_fd, os.getpgrp())
time.sleep(self.sleep_time)
def write(self, byte_string):
self.horizontal_line("write '%s'" % byte_string.decode("utf-8"))
- os.write(self.master_fd, byte_string)
+ os.write(self.controller_fd, byte_string)
def wait(self, condition):
start = time.time()
@@ -156,50 +156,51 @@ def wait_running(self):
class PseudoShell(object):
- """Sets up master and child processes with a PTY.
+ """Sets up controller and minion processes with a PTY.
You can create a ``PseudoShell`` if you want to test how some
function responds to terminal input. This is a pseudo-shell from a
- job control perspective; ``master_function`` and ``child_function``
- are set up with a pseudoterminal (pty) so that the master can drive
- the child through process control signals and I/O.
+ job control perspective; ``controller_function`` and ``minion_function``
+ are set up with a pseudoterminal (pty) so that the controller can drive
+ the minion through process control signals and I/O.
The two functions should have signatures like this::
- def master_function(proc, ctl, **kwargs)
- def child_function(**kwargs)
+ def controller_function(proc, ctl, **kwargs)
+ def minion_function(**kwargs)
- ``master_function`` is spawned in its own process and passed three
+ ``controller_function`` is spawned in its own process and passed three
arguments:
proc
- the ``multiprocessing.Process`` object representing the child
+ the ``multiprocessing.Process`` object representing the minion
ctl
- a ``ProcessController`` object tied to the child
+ a ``ProcessController`` object tied to the minion
kwargs
keyword arguments passed from ``PseudoShell.start()``.
- ``child_function`` is only passed ``kwargs`` delegated from
+ ``minion_function`` is only passed ``kwargs`` delegated from
``PseudoShell.start()``.
- The ``ctl.master_fd`` will have its ``master_fd`` connected to
- ``sys.stdin`` in the child process. Both processes will share the
+ The ``ctl.controller_fd`` will have its ``controller_fd`` connected to
+ ``sys.stdin`` in the minion process. Both processes will share the
same ``sys.stdout`` and ``sys.stderr`` as the process instantiating
``PseudoShell``.
Here are the relationships between processes created::
._________________________________________________________.
- | Child Process | pid 2
- | - runs child_function | pgroup 2
+ | Minion Process | pid 2
+ | - runs minion_function | pgroup 2
|_________________________________________________________| session 1
^
- | create process with master_fd connected to stdin
+ | create process with controller_fd connected to stdin
| stdout, stderr are the same as caller
._________________________________________________________.
- | Master Process | pid 1
- | - runs master_function | pgroup 1
- | - uses ProcessController and master_fd to control child | session 1
+ | Controller Process | pid 1
+ | - runs controller_function | pgroup 1
+ | - uses ProcessController and controller_fd to | session 1
+ | control minion |
|_________________________________________________________|
^
| create process
@@ -207,51 +208,51 @@ def child_function(**kwargs)
._________________________________________________________.
| Caller | pid 0
| - Constructs, starts, joins PseudoShell | pgroup 0
- | - provides master_function, child_function | session 0
+ | - provides controller_function, minion_function | session 0
|_________________________________________________________|
"""
- def __init__(self, master_function, child_function):
+ def __init__(self, controller_function, minion_function):
self.proc = None
- self.master_function = master_function
- self.child_function = child_function
+ self.controller_function = controller_function
+ self.minion_function = minion_function
# these can be optionally set to change defaults
self.controller_timeout = 1
self.sleep_time = 0
def start(self, **kwargs):
- """Start the master and child processes.
+ """Start the controller and minion processes.
Arguments:
kwargs (dict): arbitrary keyword arguments that will be
- passed to master and child functions
+ passed to controller and minion functions
- The master process will create the child, then call
- ``master_function``. The child process will call
- ``child_function``.
+ The controller process will create the minion, then call
+ ``controller_function``. The minion process will call
+ ``minion_function``.
"""
self.proc = multiprocessing.Process(
- target=PseudoShell._set_up_and_run_master_function,
- args=(self.master_function, self.child_function,
+ target=PseudoShell._set_up_and_run_controller_function,
+ args=(self.controller_function, self.minion_function,
self.controller_timeout, self.sleep_time),
kwargs=kwargs,
)
self.proc.start()
def join(self):
- """Wait for the child process to finish, and return its exit code."""
+ """Wait for the minion process to finish, and return its exit code."""
self.proc.join()
return self.proc.exitcode
@staticmethod
- def _set_up_and_run_child_function(
- tty_name, stdout_fd, stderr_fd, ready, child_function, **kwargs):
- """Child process wrapper for PseudoShell.
+ def _set_up_and_run_minion_function(
+ tty_name, stdout_fd, stderr_fd, ready, minion_function, **kwargs):
+ """Minion process wrapper for PseudoShell.
Handles the mechanics of setting up a PTY, then calls
- ``child_function``.
+ ``minion_function``.
"""
# new process group, like a command or pipeline launched by a shell
@@ -266,45 +267,45 @@ def _set_up_and_run_child_function(
if kwargs.get("debug"):
sys.stderr.write(
- "child: stdin.isatty(): %s\n" % sys.stdin.isatty())
+ "minion: stdin.isatty(): %s\n" % sys.stdin.isatty())
# tell the parent that we're really running
if kwargs.get("debug"):
- sys.stderr.write("child: ready!\n")
+ sys.stderr.write("minion: ready!\n")
ready.value = True
try:
- child_function(**kwargs)
+ minion_function(**kwargs)
except BaseException:
traceback.print_exc()
@staticmethod
- def _set_up_and_run_master_function(
- master_function, child_function, controller_timeout, sleep_time,
- **kwargs):
- """Set up a pty, spawn a child process, and execute master_function.
+ def _set_up_and_run_controller_function(
+ controller_function, minion_function, controller_timeout,
+ sleep_time, **kwargs):
+ """Set up a pty, spawn a minion process, execute controller_function.
Handles the mechanics of setting up a PTY, then calls
- ``master_function``.
+ ``controller_function``.
"""
os.setsid() # new session; this process is the controller
- master_fd, child_fd = os.openpty()
- pty_name = os.ttyname(child_fd)
+ controller_fd, minion_fd = os.openpty()
+ pty_name = os.ttyname(minion_fd)
# take controlling terminal
pty_fd = os.open(pty_name, os.O_RDWR)
os.close(pty_fd)
ready = multiprocessing.Value('i', False)
- child_process = multiprocessing.Process(
- target=PseudoShell._set_up_and_run_child_function,
+ minion_process = multiprocessing.Process(
+ target=PseudoShell._set_up_and_run_minion_function,
args=(pty_name, sys.stdout.fileno(), sys.stderr.fileno(),
- ready, child_function),
+ ready, minion_function),
kwargs=kwargs,
)
- child_process.start()
+ minion_process.start()
# wait for subprocess to be running and connected.
while not ready.value:
@@ -315,30 +316,31 @@ def _set_up_and_run_master_function(
sys.stderr.write("pid: %d\n" % os.getpid())
sys.stderr.write("pgid: %d\n" % os.getpgrp())
sys.stderr.write("sid: %d\n" % os.getsid(0))
- sys.stderr.write("tcgetpgrp: %d\n" % os.tcgetpgrp(master_fd))
+ sys.stderr.write("tcgetpgrp: %d\n" % os.tcgetpgrp(controller_fd))
sys.stderr.write("\n")
- child_pgid = os.getpgid(child_process.pid)
- sys.stderr.write("child pid: %d\n" % child_process.pid)
- sys.stderr.write("child pgid: %d\n" % child_pgid)
- sys.stderr.write("child sid: %d\n" % os.getsid(child_process.pid))
+ minion_pgid = os.getpgid(minion_process.pid)
+ sys.stderr.write("minion pid: %d\n" % minion_process.pid)
+ sys.stderr.write("minion pgid: %d\n" % minion_pgid)
+ sys.stderr.write(
+ "minion sid: %d\n" % os.getsid(minion_process.pid))
sys.stderr.write("\n")
sys.stderr.flush()
- # set up master to ignore SIGTSTP, like a shell
+ # set up controller to ignore SIGTSTP, like a shell
signal.signal(signal.SIGTSTP, signal.SIG_IGN)
- # call the master function once the child is ready
+ # call the controller function once the minion is ready
try:
controller = ProcessController(
- child_process.pid, master_fd, debug=kwargs.get("debug"))
+ minion_process.pid, controller_fd, debug=kwargs.get("debug"))
controller.timeout = controller_timeout
controller.sleep_time = sleep_time
- error = master_function(child_process, controller, **kwargs)
+ error = controller_function(minion_process, controller, **kwargs)
except BaseException:
error = 1
traceback.print_exc()
- child_process.join()
+ minion_process.join()
- # return whether either the parent or child failed
- return error or child_process.exitcode
+ # return whether either the parent or minion failed
+ return error or minion_process.exitcode
diff --git a/lib/spack/spack/test/llnl/util/tty/log.py b/lib/spack/spack/test/llnl/util/tty/log.py
index f23f6637131fa5f64cd71726ff85dc1d3c5f4cd5..97950e8324b2c60828eb58e96a4192e2fb77b348 100644
--- a/lib/spack/spack/test/llnl/util/tty/log.py
+++ b/lib/spack/spack/test/llnl/util/tty/log.py
@@ -111,7 +111,7 @@ def test_log_subproc_and_echo_output_capfd(capfd, tmpdir):
# Tests below use a pseudoterminal to test llnl.util.tty.log
#
def simple_logger(**kwargs):
- """Mock logger (child) process for testing log.keyboard_input."""
+ """Mock logger (minion) process for testing log.keyboard_input."""
def handler(signum, frame):
running[0] = False
signal.signal(signal.SIGUSR1, handler)
@@ -125,7 +125,7 @@ def handler(signum, frame):
def mock_shell_fg(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.fg()
ctl.status()
ctl.wait_enabled()
@@ -134,7 +134,7 @@ def mock_shell_fg(proc, ctl, **kwargs):
def mock_shell_fg_no_termios(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.fg()
ctl.status()
ctl.wait_disabled_fg()
@@ -143,7 +143,7 @@ def mock_shell_fg_no_termios(proc, ctl, **kwargs):
def mock_shell_bg(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.bg()
ctl.status()
ctl.wait_disabled()
@@ -152,7 +152,7 @@ def mock_shell_bg(proc, ctl, **kwargs):
def mock_shell_tstp_cont(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.tstp()
ctl.wait_stopped()
@@ -163,7 +163,7 @@ def mock_shell_tstp_cont(proc, ctl, **kwargs):
def mock_shell_tstp_tstp_cont(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.tstp()
ctl.wait_stopped()
@@ -177,7 +177,7 @@ def mock_shell_tstp_tstp_cont(proc, ctl, **kwargs):
def mock_shell_tstp_tstp_cont_cont(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.tstp()
ctl.wait_stopped()
@@ -194,7 +194,7 @@ def mock_shell_tstp_tstp_cont_cont(proc, ctl, **kwargs):
def mock_shell_bg_fg(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.bg()
ctl.status()
ctl.wait_disabled()
@@ -207,7 +207,7 @@ def mock_shell_bg_fg(proc, ctl, **kwargs):
def mock_shell_bg_fg_no_termios(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.bg()
ctl.status()
ctl.wait_disabled()
@@ -220,7 +220,7 @@ def mock_shell_bg_fg_no_termios(proc, ctl, **kwargs):
def mock_shell_fg_bg(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.fg()
ctl.status()
ctl.wait_enabled()
@@ -233,7 +233,7 @@ def mock_shell_fg_bg(proc, ctl, **kwargs):
def mock_shell_fg_bg_no_termios(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background."""
+ """PseudoShell controller function for test_foreground_background."""
ctl.fg()
ctl.status()
ctl.wait_disabled_fg()
@@ -299,7 +299,7 @@ def test_foreground_background(test_fn, termios_on_or_off, tmpdir):
def synchronized_logger(**kwargs):
- """Mock logger (child) process for testing log.keyboard_input.
+ """Mock logger (minion) process for testing log.keyboard_input.
This logger synchronizes with the parent process to test that 'v' can
toggle output. It is used in ``test_foreground_background_output`` below.
@@ -330,7 +330,7 @@ def handler(signum, frame):
def mock_shell_v_v(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background_output."""
+ """Controller function for test_foreground_background_output."""
write_lock = kwargs["write_lock"]
v_lock = kwargs["v_lock"]
@@ -357,7 +357,7 @@ def mock_shell_v_v(proc, ctl, **kwargs):
def mock_shell_v_v_no_termios(proc, ctl, **kwargs):
- """PseudoShell master function for test_foreground_background_output."""
+ """Controller function for test_foreground_background_output."""
write_lock = kwargs["write_lock"]
v_lock = kwargs["v_lock"]
@@ -395,9 +395,9 @@ def test_foreground_background_output(
shell = PseudoShell(test_fn, synchronized_logger)
log_path = str(tmpdir.join("log.txt"))
- # Locks for synchronizing with child
- write_lock = multiprocessing.Lock() # must be held by child to write
- v_lock = multiprocessing.Lock() # held while master is in v mode
+ # Locks for synchronizing with minion
+ write_lock = multiprocessing.Lock() # must be held by minion to write
+ v_lock = multiprocessing.Lock() # held while controller is in v mode
with termios_on_or_off():
shell.start(
@@ -423,16 +423,16 @@ def test_foreground_background_output(
with open(log_path) as log:
log = log.read().strip().split("\n")
- # Master and child process coordinate with locks such that the child
+ # Controller and minion process coordinate with locks such that the minion
# writes "off" when echo is off, and "on" when echo is on. The
# output should contain mostly "on" lines, but may contain an "off"
- # or two. This is because the master toggles echo by sending "v" on
- # stdin to the child, but this is not synchronized with our locks.
+ # or two. This is because the controller toggles echo by sending "v" on
+ # stdin to the minion, but this is not synchronized with our locks.
# It's good enough for a test, though. We allow at most 2 "off"'s in
# the output to account for the race.
assert (
['forced output', 'on'] == uniq(output) or
- output.count("off") <= 2 # if master_fd is a bit slow
+ output.count("off") <= 2 # if controller_fd is a bit slow
)
# log should be off for a while, then on, then off