### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# lib.backgroundjobs

## Module: `lib.backgroundjobs`

Inheritance diagram for `IPython.lib.backgroundjobs`:

Manage background (threaded) jobs conveniently from an interactive shell.

This module provides a BackgroundJobManager class. This is the main class meant for public usage, it implements an object which can create and manage new background jobs.

It also provides the actual job classes managed by these BackgroundJobManager objects, see their docstrings below.

This system was inspired by discussions with B. Granger and the BackgroundCommand class described in the book Python Scripting for Computational Science, by H. P. Langtangen:

http://folk.uio.no/hpl/scripting

(although ultimately no code from this text was used, as IPython’s system is a separate implementation).

An example notebook is provided in our documentation illustrating interactive use of the system.

## Classes

### `BackgroundJobBase`

class `IPython.lib.backgroundjobs.``BackgroundJobBase`

  Bases: `threading.Thread`

  Base class to build BackgroundJob classes.

  The derived classes must implement:

  - Their own __init__, since the one here raises NotImplementedError. The

  derived constructor must call self._init() at the end, to provide common initialization.

  - A strform attribute used in calls to __str__.
  - A call() method, which will make the actual execution call and must

  return a value to be held in the ‘result’ field of the job object.

  `__init__`()
  `daemon`

    A boolean value indicating whether this thread is a daemon thread (True) or not (False).

    This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

    The entire Python program exits when no alive non-daemon threads are left.

  `getName`()
  `ident`

    Thread identifier of this thread or None if it has not been started.

    This is a nonzero integer. See the thread.get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

  `isAlive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `isDaemon`()
  `is_alive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `join`(timeout=None)

    Wait until the thread terminates.

    This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

    When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

    When the timeout argument is not present or None, the operation will block until the thread terminates.

    A thread can be join()ed many times.

    join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

  `name`

    A string used for identification purposes only.

    It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

  `run`()
  `setDaemon`(daemonic)
  `setName`(name)
  `start`()

    Start the thread’s activity.

    It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the same thread object.

  `stat_completed` = 'Completed'
  `stat_completed_c` = 2
  `stat_created` = 'Created'
  `stat_created_c` = 0
  `stat_dead` = 'Dead (Exception), call jobs.traceback() for details'
  `stat_dead_c` = -1
  `stat_running` = 'Running'
  `stat_running_c` = 1
  `traceback`()

### `BackgroundJobExpr`

class `IPython.lib.backgroundjobs.``BackgroundJobExpr`(expression, glob=None, loc=None)

  Bases: `IPython.lib.backgroundjobs.BackgroundJobBase`

  Evaluate an expression as a background job (uses a separate thread).

  `__init__`(expression, glob=None, loc=None)

    Create a new job from a string which can be fed to eval().

    global/locals dicts can be provided, which will be passed to the eval call.

  `call`()
  `daemon`

    A boolean value indicating whether this thread is a daemon thread (True) or not (False).

    This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

    The entire Python program exits when no alive non-daemon threads are left.

  `getName`()
  `ident`

    Thread identifier of this thread or None if it has not been started.

    This is a nonzero integer. See the thread.get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

  `isAlive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `isDaemon`()
  `is_alive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `join`(timeout=None)

    Wait until the thread terminates.

    This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

    When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

    When the timeout argument is not present or None, the operation will block until the thread terminates.

    A thread can be join()ed many times.

    join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

  `name`

    A string used for identification purposes only.

    It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

  `run`()
  `setDaemon`(daemonic)
  `setName`(name)
  `start`()

    Start the thread’s activity.

    It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the same thread object.

  `stat_completed` = 'Completed'
  `stat_completed_c` = 2
  `stat_created` = 'Created'
  `stat_created_c` = 0
  `stat_dead` = 'Dead (Exception), call jobs.traceback() for details'
  `stat_dead_c` = -1
  `stat_running` = 'Running'
  `stat_running_c` = 1
  `traceback`()

### `BackgroundJobFunc`

class `IPython.lib.backgroundjobs.``BackgroundJobFunc`(func, *args, **kwargs)

  Bases: `IPython.lib.backgroundjobs.BackgroundJobBase`

  Run a function call as a background job (uses a separate thread).

  `__init__`(func, *args, **kwargs)

    Create a new job from a callable object.

    Any positional arguments and keyword args given to this constructor after the initial callable are passed directly to it.

  `call`()
  `daemon`

    A boolean value indicating whether this thread is a daemon thread (True) or not (False).

    This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

    The entire Python program exits when no alive non-daemon threads are left.

  `getName`()
  `ident`

    Thread identifier of this thread or None if it has not been started.

    This is a nonzero integer. See the thread.get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

  `isAlive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `isDaemon`()
  `is_alive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `join`(timeout=None)

    Wait until the thread terminates.

    This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

    When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

    When the timeout argument is not present or None, the operation will block until the thread terminates.

    A thread can be join()ed many times.

    join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

  `name`

    A string used for identification purposes only.

    It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

  `run`()
  `setDaemon`(daemonic)
  `setName`(name)
  `start`()

    Start the thread’s activity.

    It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the same thread object.

  `stat_completed` = 'Completed'
  `stat_completed_c` = 2
  `stat_created` = 'Created'
  `stat_created_c` = 0
  `stat_dead` = 'Dead (Exception), call jobs.traceback() for details'
  `stat_dead_c` = -1
  `stat_running` = 'Running'
  `stat_running_c` = 1
  `traceback`()

### `BackgroundJobManager`

class `IPython.lib.backgroundjobs.``BackgroundJobManager`

  Bases: `object`

  Class to manage a pool of backgrounded threaded jobs.

  Below, we assume that ‘jobs’ is a BackgroundJobManager instance.

  Usage summary (see the method docstrings for details):

  > jobs.new(...) -> start a new job

  > jobs() or jobs.status() -> print status summary of all jobs

  > jobs[N] -> returns job number N.

  > foo = jobs[N].result -> assign to variable foo the result of job N

  > jobs[N].traceback() -> print the traceback of dead job N

  > jobs.remove(N) -> remove (finished) job N

  > jobs.flush() -> remove all finished jobs

  As a convenience feature, BackgroundJobManager instances provide the utility result and traceback methods which retrieve the corresponding information from the jobs list:

  > jobs.result(N) <–> jobs[N].result jobs.traceback(N) <–> jobs[N].traceback()

  While this appears minor, it allows you to use tab completion interactively on the job manager instance.

  `__init__`()
  `completed`
  `dead`
  `flush`()

    Flush all finished jobs (completed and dead) from lists.

    Running jobs are never flushed.

    It first calls _status_new(), to update info. If any jobs have completed since the last _status_new() call, the flush operation aborts.

  `new`(func_or_exp, *args, **kwargs)

    Add a new background job and start it in a separate thread.

    There are two types of jobs which can be created:

    1. Jobs based on expressions which can be passed to an eval() call. The expression must be given as a string. For example:

    > job_manager.new(‘myfunc(x,y,z=1)’[,glob[,loc]])

    The given expression is passed to eval(), along with the optional global/local dicts provided. If no dicts are given, they are extracted automatically from the caller’s frame.

    A Python statement is NOT a valid eval() expression. Basically, you can only use as an eval() argument something which can go on the right of an ‘=’ sign and be assigned to a variable.

    For example,”print ‘hello’” is not valid, but ‘2+3’ is.

    2. Jobs given a function object, optionally passing additional positional arguments:

    > job_manager.new(myfunc, x, y)

    The function is called with the given arguments.

    If you need to pass keyword arguments to your function, you must supply them as a dict named kw:

    > job_manager.new(myfunc, x, y, kw=dict(z=1))

    The reason for this assymmetry is that the new() method needs to maintain access to its own keywords, and this prevents name collisions between arguments to new() and arguments to your own functions.

    In both cases, the result is stored in the job.result field of the background job object.

    You can set daemon attribute of the thread by giving the keyword argument daemon.

    Notes and caveats:

    1. All threads running share the same standard output. Thus, if your background jobs generate output, it will come out on top of whatever you are currently writing. For this reason, background jobs are best used with silent functions which simply return their output.

    2. Threads also all work within the same global namespace, and this system does not lock interactive variables. So if you send job to the background which operates on a mutable object for a long time, and start modifying that same mutable object interactively (or in another backgrounded job), all sorts of bizarre behaviour will occur.

    3. If a background job is spending a lot of time inside a C extension module which does not release the Python Global Interpreter Lock (GIL), this will block the IPython prompt. This is simply because the Python interpreter can only switch between threads at Python bytecodes. While the execution is inside C code, the interpreter must simply wait unless the extension module releases the GIL.

    4. There is no way, due to limitations in the Python threads library, to kill a thread once it has started.

  `remove`(num)

    Remove a finished (completed or dead) job.

  `result`(N) → return the result of job N.
  `running`
  `status`(verbose=0)

    Print a status of all jobs currently being managed.

  `traceback`(job=None)

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »