passagemath-categories 10.6.32__cp314-cp314t-musllinux_1_2_aarch64.whl

sage/interfaces/process.pxd

@@ -0,0 +1,5 @@
+# sage_setup: distribution = sagemath-categories
+cdef class ContainChildren():
+    cdef int parentpid
+    cdef int exitcode, exceptcode
+    cdef bint silent

sage/interfaces/process.pyx

@@ -0,0 +1,288 @@
+# sage_setup: distribution = sagemath-categories
+"""
+Utilities for subprocess management
+"""
+
+# ***************************************************************************
+#       Copyright (C) 2015 Jeroen Demeyer <jdemeyer@cage.ugent.be>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ***************************************************************************
+
+import errno
+import signal
+import sys
+
+from contextlib import contextmanager
+
+IF UNAME_SYSNAME == "Linux" or UNAME_SYSNAME == "Darwin":
+
+    from posix.unistd cimport getpid, _exit
+
+ELSE:
+
+    def getpid():
+        return 0
+
+    def _exit():
+        sys.exit(0)
+
+from cysignals.pselect import PSelecter
+from cysignals.pysignals import changesignal
+
+
+cdef class ContainChildren():
+    """
+    Context manager which will ensure that all forked child processes
+    will be forced to exit if they try to exit the context.
+
+    This can be used as a guard against race conditions, where a child
+    process wants to ``fork`` and ``exec`` but it gets interrupted after
+    the ``fork`` but before the ``exec``. In such situations, the child
+    would raise ``KeyboardInterrupt`` and execute code which is really
+    meant for the parent process.
+
+    INPUT:
+
+    - ``exitcode`` -- integer (default: 0); exit code to use when a
+      child process tries to exit the with block normally (not due to
+      an exception)
+
+    - ``exceptcode`` -- integer (default: 1); exit code to use when a
+      child process tries to exit the with block due to an exception
+
+    - ``silent`` -- boolean (default: ``False``); if ``False``, print
+      exceptions raised by the child process
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.process import ContainChildren
+        sage: pid = os.getpid()
+        sage: with ContainChildren():
+        ....:     child = os.fork()
+        sage: assert pid == os.getpid()  # We are the parent process
+
+    By default, exceptions raised by the child process are printed::
+
+        sage: with ContainChildren():
+        ....:     child = os.fork()
+        ....:     if child == 0:
+        ....:         raise RuntimeError("Exception raised by child")
+        ....:     _ = os.waitpid(child, 0r)
+        Exception raised by child process with pid=...:
+        Traceback (most recent call last):
+        ...
+        RuntimeError: Exception raised by child
+
+    The same example with ``silent=True`` does not show the exception::
+
+        sage: with ContainChildren(silent=True):
+        ....:     child = os.fork()
+        ....:     if child == 0:
+        ....:         raise RuntimeError("Exception raised by child")
+        ....:     _ = os.waitpid(child, 0r)
+    """
+    def __init__(self, exitcode=0, exceptcode=1, silent=False):
+        """
+        TESTS:
+
+        Check that the exit codes work properly::
+
+            sage: from sage.interfaces.process import ContainChildren
+            sage: with ContainChildren(exitcode=11):
+            ....:     child = os.fork()
+            sage: pid, st = os.waitpid(child, 0r)
+            sage: os.WEXITSTATUS(st)
+            11
+            sage: with ContainChildren(exceptcode=12, silent=True):
+            ....:     child = os.fork()
+            ....:     if child == 0:
+            ....:         raise RuntimeError("Exception raised by child")
+            sage: pid, st = os.waitpid(child, 0r)
+            sage: os.WEXITSTATUS(st)
+            12
+        """
+        self.exitcode = exitcode
+        self.exceptcode = exceptcode
+        self.silent = silent
+
+    def __enter__(self):
+        """
+        Store the current PID and flush the standard output and error
+        streams.
+
+        TESTS:
+
+        The flushing solves the following double-output problem::
+
+            sage: try:
+            ....:     _ = sys.stdout.write("X ")
+            ....:     if os.fork() == 0:
+            ....:         _ = sys.stdout.write("Y ")
+            ....:         sys.stdout.flush()
+            ....:         os._exit(0)
+            ....:     sleep(float(0.5))  # Give the child process time
+            ....:     print("Z")
+            ....: finally:
+            ....:     pass
+            X Y X Z
+
+        With ``ContainChildren()``, no additional flushes are needed::
+
+            sage: from sage.interfaces.process import ContainChildren
+            sage: try:
+            ....:     _ = sys.stdout.write("X ")
+            ....:     with ContainChildren():
+            ....:         _ = sys.stdout.write("Y ")
+            ....:     sleep(float(0.5))  # Give the child process time
+            ....:     print("Z")
+            ....: finally:
+            ....:     pass
+            X Y Z
+        """
+        self.parentpid = getpid()
+        # Since we're probably forking, it's a good idea to flush
+        # output streams now.
+        sys.stdout.flush()
+        sys.stderr.flush()
+
+    def __exit__(self, *exc):
+        """
+        TESTS:
+
+        Check that exceptions raised by the parent work normally::
+
+            sage: from sage.interfaces.process import ContainChildren
+            sage: with ContainChildren():
+            ....:     assert os.fork() == 0
+            Traceback (most recent call last):
+            ...
+            AssertionError
+        """
+        cdef int pid = getpid()
+        if pid == self.parentpid:
+            # We are the parent process
+            return
+
+        # We are a child process!
+        cdef int exitcode = self.exitcode
+        try:
+            if exc[0] is not None:  # Exception was raised
+                exitcode = self.exceptcode
+                if not self.silent:
+                    sys.stderr.write("Exception raised by child process with pid=%s:\n" % pid)
+                    import traceback
+                    traceback.print_exception(*exc)
+            sys.stdout.flush()
+            sys.stderr.flush()
+        finally:
+            # This ensures that we can never exit this function alive.
+            _exit(exitcode)
+
+
+@contextmanager
+def terminate(sp, interval=1, signals=[signal.SIGTERM, signal.SIGKILL]):
+    r"""
+    Context manager that terminates or kills the given `subprocess.Popen`
+    when it is no longer needed, in case the process does not end on its
+    own.
+
+    Before sending signals, the standard I/O pipes are closed, which
+    might cause the application to quit by itself.
+
+    INPUT:
+
+    - ``sp`` -- a `subprocess.Popen` instance
+    - ``interval`` -- float (default: 1); interval in seconds between
+      termination attempts
+    - ``signals`` -- (list, default [signal.SIGTERM, signal.SIGKILL]) the
+      signals to send the process in order to terminate it
+
+    EXAMPLES:
+
+    A still-running process will be terminated upon exiting the terminate
+    context::
+
+        sage: import signal, sys
+        sage: from subprocess import Popen, PIPE
+        sage: from sage.interfaces.process import terminate
+        sage: cmd = [sys.executable, '-c', 'import sys; print("y")\n'
+        ....:                              'sys.stdout.flush()\n'
+        ....:                              'while True: pass']
+        sage: sp = Popen(cmd, stdout=PIPE, encoding='ascii')
+        sage: with terminate(sp, interval=0.2):
+        ....:     print(sp.stdout.readline())
+        y
+        <BLANKLINE>
+        sage: sp.wait() == -signal.SIGTERM
+        True
+
+    If for any reason the process can't be terminated normally, a ``kill()``
+    is attempted::
+
+        sage: cmd[2] = 'from signal import signal, SIGTERM, SIG_IGN\n' \
+        ....:          'import sys\n' \
+        ....:          'signal(SIGTERM, SIG_IGN)\n' \
+        ....:          'print("y"); sys.stdout.flush()\n' \
+        ....:          'while True: pass'
+        sage: sp = Popen(cmd, stdout=PIPE, encoding='ascii')
+        sage: with terminate(sp, interval=0.2):
+        ....:     print(sp.stdout.readline())
+        y
+        <BLANKLINE>
+        sage: sp.wait() == -signal.SIGKILL
+        True
+
+    If the process dies by itself, we don't need to wait too long::
+
+        sage: cmd = [sys.executable, '-c', 'from time import sleep; sleep(0.5)']
+        sage: t0 = walltime()
+        sage: sp = Popen(cmd)
+        sage: with terminate(sp, interval=5.0):
+        ....:     pass
+        sage: t = walltime() - t0
+        sage: t <= 4.0 or t
+        True
+
+    If the process is already dead, nothing happens::
+
+        sage: t0 = walltime()
+        sage: with terminate(sp, interval=5.0):
+        ....:     raise Exception("just testing")
+        sage: t = walltime() - t0
+        sage: t <= 4.0 or t
+        True
+    """
+    try:
+        yield sp
+    finally:
+        # This "with" block ensures that SIGCHLD will certainly
+        # interrupt the sel.sleep() call without race conditions.
+        with PSelecter([signal.SIGCHLD]) as sel, \
+                changesignal(signal.SIGCHLD, lambda *args: None):
+            if sp.poll() is not None:
+                return
+
+            for stream in [sp.stdin, sp.stdout, sp.stderr]:
+                try:
+                    stream.close()
+                except Exception:
+                    pass
+
+            for sig in signals:
+                sel.sleep(interval)
+                if sp.poll() is not None:
+                    return
+                try:
+                    # Try to force the process to end
+                    sp.send_signal(sig)
+                except OSError as exc:
+                    if exc.errno == errno.ESRCH:
+                        # No such process => process is dead
+                        return
+                    else:
+                        raise

sage/interfaces/quit.py

@@ -0,0 +1,167 @@
+# sage_setup: distribution = sagemath-categories
+"""
+Quitting interfaces
+"""
+
+################################################################################
+#       Copyright (C) 2010 William Stein <wstein@gmail.com>
+#
+#  Distributed under the terms of (any version of) the GNU
+#  General Public License (GPL). The full text of the GPL is available at:
+#
+#                  https://www.gnu.org/licenses/
+################################################################################
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+from sage.env import DOT_SAGE, HOSTNAME
+from sage.misc.cachefunc import cached_function
+
+if TYPE_CHECKING:
+    from weakref import ReferenceType
+
+    from sage.interfaces.expect import Expect
+
+
+@cached_function
+def sage_spawned_process_file() -> str:
+    """
+    EXAMPLES::
+
+        sage: from sage.interfaces.quit import sage_spawned_process_file
+        sage: len(sage_spawned_process_file()) > 1
+        True
+    """
+    from sage.misc.temporary_file import tmp_dir
+    return os.path.join(tmp_dir(), "spawned_processes")
+
+
+def register_spawned_process(pid: int, cmd: str = "") -> None:
+    """
+    Write a line to the ``spawned_processes`` file with the given
+    ``pid`` and ``cmd``.
+    """
+    if cmd != "":
+        cmd = cmd.strip().split()[0]
+    # This is safe, since only this process writes to this file.
+    try:
+        with open(sage_spawned_process_file(), "a") as file:
+            file.write("%s %s\n" % (pid, cmd))
+    except OSError:
+        pass
+
+
+expect_objects: list[ReferenceType[Expect]] = []
+
+
+def expect_quitall(verbose: bool = False) -> None:
+    """
+    EXAMPLES::
+
+        sage: sage.interfaces.quit.expect_quitall()
+        sage: gp.eval('a=10')                                                           # needs sage.libs.pari
+        '10'
+        sage: gp('a')                                                                   # needs sage.libs.pari
+        10
+        sage: sage.interfaces.quit.expect_quitall()
+        sage: gp('a')                                                                   # needs sage.libs.pari
+        a
+        sage: sage.interfaces.quit.expect_quitall(verbose=True)                         # needs sage.libs.pari
+        Exiting PARI/GP interpreter with PID ... running .../gp --fast --emacs --quiet --stacksize 10000000
+    """
+    for reference in expect_objects:
+        process = reference()
+        if process is not None:
+            try:
+                process.quit(verbose=verbose)
+            except RuntimeError:
+                pass
+    kill_spawned_jobs()
+
+
+def kill_spawned_jobs(verbose: bool = False):
+    """
+    INPUT:
+
+    - ``verbose`` -- boolean (default: ``False``); if ``True``, display a
+      message each time a process is sent a kill signal
+
+    EXAMPLES::
+
+        sage: gp.eval('a=10')                                                           # needs sage.libs.pari
+        '10'
+        sage: sage.interfaces.quit.kill_spawned_jobs(verbose=False)
+        sage: sage.interfaces.quit.expect_quitall()
+        sage: gp.eval('a=10')                                                           # needs sage.libs.pari
+        '10'
+        sage: sage.interfaces.quit.kill_spawned_jobs(verbose=True)                      # needs sage.libs.pari
+        Killing spawned job ...
+
+    After doing the above, we do the following to avoid confusion in other doctests::
+
+        sage: sage.interfaces.quit.expect_quitall()
+    """
+    fname = sage_spawned_process_file()
+    if not os.path.exists(fname):
+        return
+
+    with open(fname) as file:
+        for line in file:
+            i = line.find(" ")
+            pid = line[:i].strip()
+            try:
+                if verbose:
+                    print("Killing spawned job %s" % pid)
+                if sys.platform == "win32":
+                    # From https://stackoverflow.com/a/47756757/873661
+                    subprocess.call(["taskkill", "/F", "/T", "/PID", pid])
+                else:
+                    os.killpg(int(pid), 9)
+            except OSError:
+                pass
+
+
+def is_running(pid: int) -> bool:
+    """
+    Return ``True`` if and only if there is a process with id pid running.
+    """
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def invalidate_all() -> None:
+    """
+    Invalidate all of the expect interfaces.
+
+    This is used, e.g., by the fork-based ``@parallel`` decorator.
+
+    EXAMPLES::
+
+        sage: # needs sage.libs.pari sage.symbolic
+        sage: a = maxima(2); b = gp(3)
+        sage: a, b
+        (2, 3)
+        sage: sage.interfaces.quit.invalidate_all()
+        sage: a
+        (invalid Maxima object -- The maxima session in which this object was defined is no longer running.)
+        sage: b
+        (invalid PARI/GP interpreter object -- The pari session in which this object was defined is no longer running.)
+
+    However the maxima and gp sessions should still work out, though with their state reset::
+
+        sage: a = maxima(2); b = gp(3)                                                  # needs sage.libs.pari sage.symbolic
+        sage: a, b                                                                      # needs sage.libs.pari sage.symbolic
+        (2, 3)
+    """
+    for reference in expect_objects:
+        process = reference()
+        if process:
+            process.detach()