{"id":8055,"library":"cysignals","title":"cysignals","description":"cysignals is a Python library designed for robust interrupt and signal handling within Cython code. It provides mechanisms to ensure that long-running Cython computations can be interrupted (e.g., via CTRL-C) and offers a Python interface for managing OS-level signal handlers and system calls like `pselect()` and `sigprocmask()`. The library is currently at version 1.12.6, actively maintained by the SageMath community, and receives regular updates to support newer Python and Cython versions.","status":"active","version":"1.12.6","language":"en","source_language":"en","source_url":"https://github.com/sagemath/cysignals","tags":["cython","signals","interrupts","error-handling","sagemath"],"install":[{"cmd":"pip install cysignals","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.12 or newer for current versions.","package":"python","optional":false},{"reason":"Used for compiling Cython extensions; requires Cython 3.1 or newer.","package":"cython","optional":false},{"reason":"Python build backend (PEP 517) used in the build process.","package":"meson-python","optional":true}],"imports":[{"note":"Used in Cython code for interrupt checks in mixed Cython/Python loops.","symbol":"sig_check","correct":"from cysignals.signals cimport sig_check"},{"note":"Used in Cython code to guard long-running C library calls or pure Cython blocks.","symbol":"sig_on","correct":"from cysignals.signals cimport sig_on"},{"note":"Must be paired with sig_on() to release signal handling context.","symbol":"sig_off","correct":"from cysignals.signals cimport sig_off"},{"note":"Used within a sig_on() block to report errors from C libraries as Python exceptions.","symbol":"sig_error","correct":"from cysignals.signals cimport sig_error"},{"note":"Context manager to temporarily change a Python-level and OS-level signal handler.","symbol":"changesignal","correct":"from cysignals.pysignals import changesignal"}],"quickstart":{"code":"import cython\nimport os\n\n# This code needs to be in a .pyx file to be compiled by Cython\n# For demonstration, we simulate compilation by directly defining in Python context\n# In a real scenario, this would be compiled with a setup.py/pyproject.toml\n\ndef run_interruptible_loop(n_iterations: int):\n    try:\n        # In a .pyx file, you would use: from cysignals.signals cimport sig_check\n        # For this quickstart, we use a mock for illustration in a .py file\n        # In practice, you'd compile this Cython code.\n        # This is a simplified representation of how sig_check would be used.\n\n        # Simulate Cython compilation and execution\n        print(f\"Running a loop for {n_iterations} iterations. Try pressing CTRL+C.\")\n        for i in range(n_iterations):\n            # Imagine this is within a Cython function containing a `sig_check()` call\n            if i % 1_000_000 == 0:\n                print(f\"  Iteration {i}\")\n            # A real sig_check() would check for interrupts and raise KeyboardInterrupt\n            # if os.getenv('CYSIGNALS_SIMULATE_INTERRUPT') and i == n_iterations // 2:\n            #     raise KeyboardInterrupt(\"Simulated interrupt\")\n            \n            # Simulate a small amount of work\n            _ = i * i\n\n        print(\"Loop completed without interruption.\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLoop interrupted by user (KeyboardInterrupt caught)!\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    # This part would run the compiled Cython module\n    # For this example, we directly call the Python function simulating the loop.\n    run_interruptible_loop(10_000_000)","lang":"python","description":"This quickstart demonstrates the core interrupt handling mechanism using `sig_check()`. While `sig_check()` is a Cython cimport, the Python code here illustrates its effect by demonstrating an interruptible long-running loop. In actual use, `sig_check()` would be placed within Cython `def`, `cdef`, or `cpdef` functions to allow graceful interruption. A real-world example would involve compiling a `.pyx` file containing the `cimport` and `sig_check()` calls."},"warnings":[{"fix":"Review `cysignals` documentation for alternative error handling mechanisms if relying on C library callbacks. If `_pari_version` was used, it now returns `None`.","message":"cysignals versions 1.12.0 and later removed the optional compile-time dependency on PARI/GP. If your Cython code relied on the `_pari_version` function or the `sig_error()` mechanism for PARI, you will need to adjust your build process or error handling.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Upgrade your Python environment to 3.12 or newer. If you need to support older Python versions, you must use an older cysignals release compatible with your Python version (e.g., 1.11.3 for Python 3.12 support).","message":"Version 1.12.6 dropped support for older Python versions, now requiring Python 3.12 or newer. Previous versions (e.g., 1.11.0) similarly dropped Python 2 support and bumped the minimum to 3.6.","severity":"breaking","affected_versions":">=1.12.6, >=1.11.0"},{"fix":"Ensure `sig_on()` and `sig_off()` form a correct pair within a single function's execution path. Avoid Python API calls inside the `sig_on()` block. Prefer `sig_check()` for mixed Python/Cython loops.","message":"When using `sig_on()` and `sig_off()` in Cython, they must always be called in pairs, and `sig_off()` must be executed before the function calling `sig_on()` returns (including all return or raise paths). The code within `sig_on()` and `sig_off()` should be pure C or Cython, as calling Python code or manipulating Python objects can lead to corrupted internal state if an interrupt occurs. Use `sig_check()` if you are unsure.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `_FORTIFY_SOURCE` is not defined or is set to `0` during compilation of `cysignals` and modules linking against it. This typically involves adjusting CFLAGS.","message":"Compiling cysignals with `_FORTIFY_SOURCE` enabled can lead to compilation errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your build environment is configured to use Meson. If encountering `setuptools`-related build errors, consider upgrading your packaging tools or reviewing your build configuration to align with Meson.","message":"The build system for cysignals transitioned to Meson in version 1.12.0. Older `setuptools`-based build practices might encounter issues with newer `cysignals` versions or Python packaging tooling.","severity":"deprecated","affected_versions":">=1.12.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Disable `_FORTIFY_SOURCE` during compilation. This typically involves adding `-U_FORTIFY_SOURCE` or `-D_FORTIFY_SOURCE=0` to CFLAGS in your build configuration.","cause":"The `_FORTIFY_SOURCE` macro, often enabled by default in some compilation environments for security, conflicts with cysignals' low-level signal handling.","error":"error: cysignals must be compiled without _FORTIFY_SOURCE"},{"fix":"Navigate to the source directory of cysignals and run `make distclean` before attempting to configure or build again. For newer Meson-based builds, you might need to remove the build directory.","cause":"This error occurs when attempting to configure or build cysignals after a previous (possibly failed) build attempt without proper cleanup, especially in older build systems.","error":"configure: error: source directory already configured; run \"make distclean\" there first"},{"fix":"Inspect the Cython code for potential memory issues or improper handling of C library calls. Ensure all critical C/Cython blocks are properly wrapped with `sig_on()` and `sig_off()` calls, and that no Python interaction occurs within these blocks. Debug with GDB for a more detailed backtrace if cysignals' crash hook does not provide enough information.","cause":"A segmentation fault (SIGSEGV) occurred within a compiled module, likely a Cython extension, and was not properly handled by `cysignals`' `sig_on()`/`sig_off()` context. This indicates a low-level memory error or an unhandled signal in native code.","error":"Unhandled SIGSEGV during signal handling. This probably occurred because a *compiled* module has a bug in it and is not properly wrapped with sig_on(), sig_off(). Python will now terminate."},{"fix":"Ensure `Cython` and a C compiler (like GCC or Clang) are installed and accessible in your environment. For newer Python versions and `cysignals`, verify `meson-python` is available. Review the full error output for specific compiler messages. Consider `pip install --no-build-isolation cysignals` as a diagnostic step or to work around build environment issues.","cause":"This generic error during `pip install` often indicates a compilation failure of the Cython extensions, potentially due to missing build dependencies (e.g., Cython, a C compiler), environment misconfiguration, or issues with older `setuptools`-based builds interacting with newer Python versions/packaging standards.","error":"ERROR: Command errored out with exit status 1: command: /path/to/python -u -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = ... /setup.py' install ..."}]}