====== stopit

Raise asynchronous exceptions in other threads, control the timeout of blocks or callables with two context managers and two decorators.

.. attention:: API Changes

Users of 1.0.0 should upgrade their source code:

• stopit.Timeout is renamed stopit.ThreadingTimeout
• stopit.timeoutable is renamed stopit.threading_timeoutable

Explications follow below...

.. contents::

Overview

This module provides:

• a function that raises an exception in another thread, including the main thread.

• two context managers that may stop its inner block activity on timeout.

• two decorators that may stop its decorated callables on timeout.

Developed and tested with CPython 2.6, 2.7, 3.3 and 3.4 on MacOSX. Should work on any OS (xBSD, Linux, Windows) except when explicitly mentioned.

.. note::

Signal based timeout controls, namely SignalTimeout context manager and signal_timeoutable decorator won't work in Windows that has no support for signal.SIGALRM. Any help to work around this is welcome.

Installation

Using stopit in your application

Both work identically:

.. code:: bash

easy_install stopit pip install stopit

Developing stopit

.. code:: bash

You should prefer forking if you have a Github account

git clone https://github.com/glenfant/stopit.git cd stopit python setup.py develop

Does it work for you ?

python setup.py test

Public API

Exception

stopit.TimeoutException ...........................

A stopit.TimeoutException may be raised in a timeout context manager controlled block.

This exception may be propagated in your application at the end of execution of the context manager controlled block, see the swallow_ex parameter of the context managers.

Note that the stopit.TimeoutException is always swallowed after the execution of functions decorated with xxx_timeoutable(...). Anyway, you may catch this exception within the decorated function.

Threading based resources

.. warning::

Threading based resources will only work with CPython implementations since we use CPython specific low level API. This excludes Iron Python, Jython, Pypy, ...

Will not stop the execution of blocking Python atomic instructions that acquire the GIL. In example, if the destination thread is actually executing a time.sleep(20), the asynchronous exception is effective after its execution.

stopit.async_raise ......................

A function that raises an arbitrary exception in another thread

async_raise(tid, exception)

• tid is the thread identifier as provided by the ident attribute of a thread object. See the documentation of the threading module for further information.

• exception is the exception class or object to raise in the thread.

stopit.ThreadingTimeout ...........................

A context manager that "kills" its inner block execution that exceeds the provided time.

ThreadingTimeout(seconds, swallow_exc=True)

• seconds is the number of seconds allowed to the execution of the context managed block.

• swallow_exc : if False, the possible stopit.TimeoutException will be re-raised when quitting the context managed block. Attention: a True value does not swallow other potential exceptions.

Methods and attributes

of a stopit.ThreadingTimeout context manager.

.. list-table:: :header-rows: 1

• • Method / Attribute
  • Description
• • .cancel()
  • Cancels the timeout control. This method is intended for use within the block that's under timeout control, specifically to cancel the timeout control. Means that all code executed after this call may be executed till the end.
• • .state
  • This attribute indicated the actual status of the timeout control. It may take the value of the EXECUTED, EXECUTING, TIMED_OUT, INTERRUPTED or CANCELED attributes. See below.
• • .EXECUTING
  • The timeout control is under execution. We are typically executing within the code under control of the context manager.
• • .EXECUTED
  • Good news: the code under timeout control completed normally within the assigned time frame.
• • .TIMED_OUT
  • Bad news: the code under timeout control has been sleeping too long. The objects supposed to be created or changed within the timeout controlled block should be considered as non existing or corrupted. Don't play with them otherwise informed.
• • .INTERRUPTED
  • The code under timeout control may itself raise explicit stopit.TimeoutException for any application logic reason that may occur. This intentional exit can be spotted from outside the timeout controlled block with this state value.
• • .CANCELED
  • The timeout control has been intentionally canceled and the code running under timeout control did complete normally. But perhaps after the assigned time frame.

A typical usage:

.. code:: python

import stopit

...

with stopit.ThreadingTimeout(10) as to_ctx_mgr: assert to_ctx_mgr.state == to_ctx_mgr.EXECUTING # Something potentially very long but which # ...

OK, let's check what happened

if to_ctx_mgr.state == to_ctx_mgr.EXECUTED: # All's fine, everything was executed within 10 seconds elif to_ctx_mgr.state == to_ctx_mgr.EXECUTING: # Hmm, that's not possible outside the block elif to_ctx_mgr.state == to_ctx_mgr.TIMED_OUT: # Eeek the 10 seconds timeout occurred while executing the block elif to_ctx_mgr.state == to_ctx_mgr.INTERRUPTED: # Oh you raised specifically the TimeoutException in the block elif to_ctx_mgr.state == to_ctx_mgr.CANCELED: # Oh you called to_ctx_mgr.cancel() method within the block but it # executed till the end else: # That's not possible

Notice that the context manager object may be considered as a boolean indicating (if True) that the block executed normally:

.. code:: python

if to_ctx_mgr: # Yes, the code under timeout control completed # Objects it created or changed may be considered consistent

stopit.threading_timeoutable ................................

A decorator that kills the function or method it decorates, if it does not return within a given time frame.

stopit.threading_timeoutable([default [, timeout_param]])

• default is the value to be returned by the decorated function or method of when its execution timed out, to notify the caller code that the function did not complete within the assigned time frame.

  If this parameter is not provided, the decorated function or method will return a None value when its execution times out.

  .. code:: python

  @stopit.threading_timeoutable(default='not finished') def infinite_loop(): # As its name says...

  result = infinite_loop(timeout=5) assert result == 'not finished'

• timeout_param: The function or method you have decorated may require a timeout named parameter for whatever reason. This empowers you to change the name of the timeout parameter in the decorated function signature to whatever suits, and prevent a potential naming conflict.

  .. code:: python

  @stopit.threading_timeoutable(timeout_param='my_timeout') def some_slow_function(a, b, timeout='whatever'): # As its name says...

  result = some_slow_function(1, 2, timeout="something", my_timeout=2)

About the decorated function ............................

or method...

As you noticed above, you just need to add the timeout parameter when calling the function or method. Or whatever other name for this you chose with the timeout_param of the decorator. When calling the real inner function or method, this parameter is removed.

Signaling based resources

.. warning::

Using signaling based resources will not work under Windows or any OS that's not based on Unix.

stopit.SignalTimeout and stopit.signal_timeoutable have exactly the same API as their respective threading based resources, namely stopit.ThreadingTimeout_ and stopit.threading_timeoutable_.

See the comparison chart_ that warns on the more or less subtle differences between the Threading based resources_ and the Signaling based resources_.

Logging

The stopit named logger emits a warning each time a block of code execution exceeds the associated timeout. To turn logging off, just:

.. code:: python

import logging stopit_logger = logging.getLogger('stopit') stopit_logger.setLevel(logging.ERROR)

.. _comparison chart:

Comparing thread based and signal based timeout control

.. list-table:: :header-rows: 1

• • Feature
  • Threading based resources
  • Signaling based resources
• • GIL
  • Can't interrupt a long Python atomic instruction. e.g. if time.sleep(20.0) is actually executing, the timeout will take effect at the end of the execution of this line.
  • Don't care of it
• • Thread safety
  • Yes : Thread safe as long as each thread uses its own ThreadingTimeout context manager or threading_timeoutable decorator.
  • Not thread safe. Could yield unpredictable results in a multithreads application.
• • Nestable context managers
  • Yes : you can nest threading based context managers
  • No : never nest a signaling based context manager in another one. The innermost context manager will automatically cancel the timeout control of outer ones.
• • Accuracy