docs/source/development/notification_blueprint.txt

.. _notification:

==========================================
IPython.kernel.core.notification blueprint
==========================================

Overview
========

The :mod:`IPython.kernel.core.notification` module will provide a simple
implementation of a notification center and support for the observer pattern
within the :mod:`IPython.kernel.core`. The main intended use case is to
provide notification of Interpreter events to an observing frontend during the
execution of a single block of code.

Functional Requirements
=======================

The notification center must:

* Provide synchronous notification of events to all registered observers.

* Provide typed or labeled notification types.

* Allow observers to register callbacks for individual or all notification
  types.

* Allow observers to register callbacks for events from individual or all
  notifying objects.

* Notification to the observer consists of the notification type, notifying
  object and user-supplied extra information [implementation: as keyword
  parameters to the registered callback].

* Perform as O(1) in the case of no registered observers.

* Permit out-of-process or cross-network extension.
    
What's not included
===================

As written, the :mod:`IPython.kernel.core.notificaiton` module does not:

* Provide out-of-process or network notifications (these should be handled by
  a separate, Twisted aware module in :mod:`IPython.kernel`).

* Provide zope.interface-style interfaces for the notification system (these
  should also be provided by the :mod:`IPython.kernel` module).
    
Use Cases
=========

The following use cases describe the main intended uses of the notificaiton module and illustrate the main success scenario for each use case:

    1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code::

        from IPython.kernel.core.notification import NotificationCenter
        center = NotificationCenter.sharedNotificationCenter
        center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification)
    
    and elsewhere in his front end::

        def stdout_notification(self, type, notifying_object, out_string=None):
            self.writeStdOut(out_string)
    
If everything works, the Interpreter will (according to its published API)
fire a notification via the
:data:`IPython.kernel.core.notification.sharedCenter` of type
:const:`STD_OUT_NOTIFICATION_TYPE` before writing anything to stdout [it's up
to the Intereter implementation to figure out when to do this]. The
notificaiton center will then call the registered callbacks for that event
type (in this case, Dwight's frontend's stdout_notification method). Again,
according to its API, the Interpreter provides an additional keyword argument
when firing the notificaiton of out_string, a copy of the string it will write
to stdout.

Like magic, Dwight's frontend is able to provide output, even during
long-running calculations. Now if Jim could just convince Dwight to use
Twisted...

    2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is stuck in the stone age, his frontend will be written in a new Fortran-like dialect of python and will run only from the command line. Because he doesn't need any fancy notification system and is used to worrying about every cycle on his rat-wheel powered mini, Boss Hog is adamant that the new notification system not produce any performance penalty. As they say in Hazard county, there's no such thing as a free lunch. If he wanted zero overhead, he should have kept using IPython 0.8. Instead, those tricky Duke boys slide in a suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module that imparts only a constant (and small) performance penalty when the Interpreter (or any other object) fires an event for which there are no registered observers. Of course, the same notificaiton-enabled Interpreter can then be used in frontends that require notifications, thus saving the IPython project from a nasty civil war.
    
    3. Barry is wrting a frontend for the IPython project. Because Barry's front end is the *new hotness*, it uses an asynchronous event model to communicate with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the :mod:`IPython.kernel.core.notification` module, Barry's frontend can register for notifications from the interpreter that are delivered asynchronously. Even if Barry's frontend is running on a separate process or even host from the Interpreter, the notifications are delivered, as if by dark and twisted magic. Just like Dwight's frontend, Barry's frontend can now recieve notifications of e.g. writing to stdout/stderr, opening/closing an external file, an exception in the executing code, etc.