Browse files

remove obsolete 'notification blueprint' doc

  • Loading branch information...
minrk committed Jun 30, 2011
1 parent 5093b1b commit 3f04e67e26ba87e2ff8a09402b506582d758cb24
Showing with 0 additions and 124 deletions.
  1. +0 −1 docs/source/development/index.txt
  2. +0 −123 docs/source/development/notification_blueprint.txt
@@ -19,7 +19,6 @@ IPython developer's guide
- notification_blueprint.txt
@@ -1,123 +0,0 @@
-.. _notification:
-IPython.kernel.core.notification blueprint
-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.notification` 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 notification
-module and illustrate the main success scenario for each use case:
-Scenario 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
-:mod:`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
-Scenario 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.
-Scenario 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 receive notifications of
-e.g. writing to stdout/stderr, opening/closing an external file, an exception
-in the executing code, etc.

0 comments on commit 3f04e67

Please sign in to comment.