cleanupd 0.9.0.2

A package providing additional object cleanup functionality.

The cleanup module provides primitives aiding in releasing of no longer used resources in an exception-safe manner. In particular, it defines defer, a function that, when used as a context manager, acts as an object for registering cleanup functions for acquired resources. An example:

client = Client()
with defer() as d:
  obj = Object()
  d.defer(obj.destroy)
  obj.register(client)
  d.defer(obj.unregister, client)
  # Alternative syntax:
  # d.defer(lambda: obj.unregister(client))
  raise Exception()

Here, the defer creates a context object d that is guaranteed to be released during block exit (even in the face of exceptions). It is used to “defer” an invocation of obj.destroy just after the object got created. This way, the object is guaranteed to be destroyed properly. Furthermore, the object is registered with a client. This registration should be undone before the object vanishes and so another “defer” operation is used to register the unregister invocation. This example also illustrates another important fact: execution of the various cleanup routines happens in reverse order of their registration. This property is important in most scenarios where resources of interest have dependencies.

Sometimes cleanup is only necessary in case an error occurs. That is, if all operations (resource acquisitions etc.) succeed, we do not want to roll back and undo a part of them. To that end, a defer context can be “released” in which case no cleanup happens after block exit. Revisiting the example above:

client = Client()
with defer() as d:
  obj = Object()
  d.defer(obj.destroy)
  obj.register(client)
  d.defer(lambda: obj.unregister(client))

  # Do some action that potentially raises an error.

  # If we got here we want to keep the object created and registered
  # with the client.
  d.release()

This mechanism not only works on the level of a context but also for individually deferred functions:

client = Client()
with defer() as d:
  obj = Object()
  f = d.defer(obj.destroy)

  # Do some action that potentially raises an error.

  f.release()

Installation

The cleanup package does not have any external dependencies. In order to use it it only needs to be made known to Python, e.g., by adding the path to the src/ directory to the PYTHONPATH environment variable.

If you are using Gentoo Linux, there is an ebuild available that can be used directly.

Support

The module is tested with Python 3. There is no work going on to ensure compatibility with Python 2.