Merging vvatsa's ipcluster-dev branch.

This merge brings in a new ssh mode for ipcluster.  Thanks to Vishal
Vatsa for this.

IPython/kernel/engineservice.py

@@ -1,903 +1,903 b''
 # encoding: utf-8
 # -*- test-case-name: IPython.kernel.tests.test_engineservice -*-
 
 """A Twisted Service Representation of the IPython core.
 
 The IPython Core exposed to the network is called the Engine.  Its
 representation in Twisted in the EngineService.  Interfaces and adapters
 are used to abstract out the details of the actual network protocol used.
 The EngineService is an Engine that knows nothing about the actual protocol
 used.
 
 The EngineService is exposed with various network protocols in modules like:
 
 enginepb.py
 enginevanilla.py
 
 As of 12/12/06 the classes in this module have been simplified greatly.  It was 
 felt that we had over-engineered things.  To improve the maintainability of the
 code we have taken out the ICompleteEngine interface and the completeEngine
 method that automatically added methods to engines.
 
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 
 import os, sys, copy
 import cPickle as pickle
 from new import instancemethod
 
 from twisted.application import service
 from twisted.internet import defer, reactor
 from twisted.python import log, failure, components
 import zope.interface as zi
 
 from IPython.kernel.core.interpreter import Interpreter
 from IPython.kernel import newserialized, error, util
 from IPython.kernel.util import printer
 from IPython.kernel.twistedutil import gatherBoth, DeferredList
 from IPython.kernel import codeutil
 
 
 #-------------------------------------------------------------------------------
 # Interface specification for the Engine
 #-------------------------------------------------------------------------------
 
 class IEngineCore(zi.Interface):
     """The minimal required interface for the IPython Engine.
     
     This interface provides a formal specification of the IPython core.
     All these methods should return deferreds regardless of what side of a
     network connection they are on.
     
     In general, this class simply wraps a shell class and wraps its return
     values as Deferred objects.  If the underlying shell class method raises
     an exception, this class should convert it to a twisted.failure.Failure
     that will be propagated along the Deferred's errback chain.
     
     In addition, Failures are aggressive.  By this, we mean that if a method
     is performing multiple actions (like pulling multiple object) if any
     single one fails, the entire method will fail with that Failure.  It is
     all or nothing. 
     """
     
     id = zi.interface.Attribute("the id of the Engine object")
     properties = zi.interface.Attribute("A dict of properties of the Engine")
     
     def execute(lines):
         """Execute lines of Python code.
         
         Returns a dictionary with keys (id, number, stdin, stdout, stderr)
         upon success.
         
         Returns a failure object if the execution of lines raises an exception.
         """
     
     def push(namespace):
         """Push dict namespace into the user's namespace.
         
         Returns a deferred to None or a failure.
         """
     
     def pull(keys):
         """Pulls values out of the user's namespace by keys.
         
         Returns a deferred to a tuple objects or a single object.
         
         Raises NameError if any one of objects doess not exist.
         """
     
     def push_function(namespace):
         """Push a dict of key, function pairs into the user's namespace.
         
         Returns a deferred to None or a failure."""
     
     def pull_function(keys):
         """Pulls functions out of the user's namespace by keys.
         
         Returns a deferred to a tuple of functions or a single function.
         
         Raises NameError if any one of the functions does not exist.
         """
     
     def get_result(i=None):
         """Get the stdin/stdout/stderr of command i.
         
         Returns a deferred to a dict with keys
         (id, number, stdin, stdout, stderr).
         
         Raises IndexError if command i does not exist.
         Raises TypeError if i in not an int.
         """
     
     def reset():
         """Reset the shell.
         
         This clears the users namespace.  Won't cause modules to be
         reloaded.  Should also re-initialize certain variables like id.
         """
     
     def kill():
         """Kill the engine by stopping the reactor."""
     
     def keys():
         """Return the top level variables in the users namspace.
         
         Returns a deferred to a dict."""
     
 
 class IEngineSerialized(zi.Interface):
     """Push/Pull methods that take Serialized objects.  
     
     All methods should return deferreds.
     """
     
     def push_serialized(namespace):
         """Push a dict of keys and Serialized objects into the user's namespace."""
     
     def pull_serialized(keys):
         """Pull objects by key from the user's namespace as Serialized.
         
         Returns a list of or one Serialized.
         
         Raises NameError is any one of the objects does not exist.
         """
     
 
 class IEngineProperties(zi.Interface):
     """Methods for access to the properties object of an Engine"""
     
     properties = zi.Attribute("A StrictDict object, containing the properties")
     
     def set_properties(properties):
         """set properties by key and value"""
     
     def get_properties(keys=None):
         """get a list of properties by `keys`, if no keys specified, get all"""
     
     def del_properties(keys):
         """delete properties by `keys`"""
     
     def has_properties(keys):
         """get a list of bool values for whether `properties` has `keys`"""
 
     def clear_properties():
         """clear the properties dict"""
     
 class IEngineBase(IEngineCore, IEngineSerialized, IEngineProperties):
     """The basic engine interface that EngineService will implement.
     
     This exists so it is easy to specify adapters that adapt to and from the
     API that the basic EngineService implements.
     """
     pass
 
 class IEngineQueued(IEngineBase):
     """Interface for adding a queue to an IEngineBase.  
     
     This interface extends the IEngineBase interface to add methods for managing
     the engine's queue.  The implicit details of this interface are that the 
     execution of all methods declared in IEngineBase should appropriately be
     put through a queue before execution. 
     
     All methods should return deferreds.
     """
     
     def clear_queue():
         """Clear the queue."""
     
     def queue_status():
         """Get the queued and pending commands in the queue."""
     
     def register_failure_observer(obs):
         """Register an observer of pending Failures.
         
         The observer must implement IFailureObserver.
         """
     
     def unregister_failure_observer(obs):
         """Unregister an observer of pending Failures."""
     
 
 class IEngineThreaded(zi.Interface):
     """A place holder for threaded commands.  
     
     All methods should return deferreds.
     """
     pass
 
 
 #-------------------------------------------------------------------------------
 # Functions and classes to implement the EngineService
 #-------------------------------------------------------------------------------
 
 
 class StrictDict(dict):
     """This is a strict copying dictionary for use as the interface to the 
     properties of an Engine.
 
     :IMPORTANT:
         This object copies the values you set to it, and returns copies to you
         when you request them.  The only way to change properties os explicitly
         through the setitem and getitem of the dictionary interface.
 
     Example:
         >>> e = get_engine(id)
         >>> L = [1,2,3]
         >>> e.properties['L'] = L
         >>> L == e.properties['L']
         True
         >>> L.append(99)
         >>> L == e.properties['L']
         False
         
         Note that getitem copies, so calls to methods of objects do not affect
         the properties, as seen here:
         
         >>> e.properties[1] = range(2)
         >>> print e.properties[1]
         [0, 1]
         >>> e.properties[1].append(2)
         >>> print e.properties[1]
         [0, 1]
     """
     def __init__(self, *args, **kwargs):
         dict.__init__(self, *args, **kwargs)
         self.modified = True
     
     def __getitem__(self, key):
         return copy.deepcopy(dict.__getitem__(self, key))
     
     def __setitem__(self, key, value):
         # check if this entry is valid for transport around the network
         # and copying
         try:
             pickle.dumps(key, 2)
             pickle.dumps(value, 2)
             newvalue = copy.deepcopy(value)
         except:
             raise error.InvalidProperty(value)
         dict.__setitem__(self, key, newvalue)
         self.modified = True
     
     def __delitem__(self, key):
         dict.__delitem__(self, key)
         self.modified = True
     
     def update(self, dikt):
         for k,v in dikt.iteritems():
             self[k] = v
     
     def pop(self, key):
         self.modified = True
         return dict.pop(self, key)
     
     def popitem(self):
         self.modified = True
         return dict.popitem(self)
     
     def clear(self):
         self.modified = True
         dict.clear(self)
     
     def subDict(self, *keys):
         d = {}
         for key in keys:
             d[key] = self[key]
         return d
     
 
 
 class EngineAPI(object):
     """This is the object through which the user can edit the `properties`
     attribute of an Engine.
     The Engine Properties object copies all object in and out of itself.
     See the EngineProperties object for details.
     """
     _fix=False
     def __init__(self, id):
         self.id = id
         self.properties = StrictDict()
         self._fix=True
     
     def __setattr__(self, k,v):
         if self._fix:
             raise error.KernelError("I am protected!")
         else:
             object.__setattr__(self, k, v)
     
     def __delattr__(self, key):
         raise error.KernelError("I am protected!")
     
 
 _apiDict = {}
 
 def get_engine(id):
     """Get the Engine API object, whcih currently just provides the properties 
     object, by ID"""
     global _apiDict
     if not _apiDict.get(id):
         _apiDict[id] = EngineAPI(id)
     return _apiDict[id]
 
 def drop_engine(id):
     """remove an engine"""
     global _apiDict
     if _apiDict.has_key(id):
         del _apiDict[id]
 
 class EngineService(object, service.Service):
     """Adapt a IPython shell into a IEngine implementing Twisted Service."""
     
     zi.implements(IEngineBase)
     name = 'EngineService'
     
     def __init__(self, shellClass=Interpreter, mpi=None):
         """Create an EngineService.
         
         shellClass: something that implements IInterpreter or core1
         mpi:        an mpi module that has rank and size attributes
         """
         self.shellClass = shellClass
         self.shell = self.shellClass()
         self.mpi = mpi
         self.id = None
         self.properties = get_engine(self.id).properties
         if self.mpi is not None:
             log.msg("MPI started with rank = %i and size = %i" % 
                 (self.mpi.rank, self.mpi.size))
             self.id = self.mpi.rank
         self._seedNamespace()
     
     # Make id a property so that the shell can get the updated id
         
     def _setID(self, id):
         self._id = id
         self.properties = get_engine(id).properties
         self.shell.push({'id': id})
     
     def _getID(self):
         return self._id
     
     id = property(_getID, _setID)
     
     def _seedNamespace(self):
         self.shell.push({'mpi': self.mpi, 'id' : self.id})
     
     def executeAndRaise(self, msg, callable, *args, **kwargs):
         """Call a method of self.shell and wrap any exception."""
         d = defer.Deferred()
         try:
             result = callable(*args, **kwargs)
         except:
             # This gives the following:
             # et=exception class
             # ev=exception class instance
             # tb=traceback object
             et,ev,tb = sys.exc_info()
             # This call adds attributes to the exception value
             et,ev,tb = self.shell.formatTraceback(et,ev,tb,msg)
             # Add another attribute
             ev._ipython_engine_info = msg
             f = failure.Failure(ev,et,None)
             d.errback(f)
         else:
             d.callback(result)
             
         return d
     
     
     # The IEngine methods.  See the interface for documentation.
     
     def execute(self, lines):
         msg = {'engineid':self.id,
                'method':'execute',
                'args':[lines]}
         d = self.executeAndRaise(msg, self.shell.execute, lines)
         d.addCallback(self.addIDToResult)
         return d
     
     def addIDToResult(self, result):
         result['id'] = self.id
         return result
     
     def push(self, namespace):
         msg = {'engineid':self.id,
                'method':'push',
                'args':[repr(namespace.keys())]}
         d = self.executeAndRaise(msg, self.shell.push, namespace)
         return d
     
     def pull(self, keys):
         msg = {'engineid':self.id,
                'method':'pull',
                'args':[repr(keys)]}
         d = self.executeAndRaise(msg, self.shell.pull, keys)
         return d
     
     def push_function(self, namespace):
         msg = {'engineid':self.id,
                'method':'push_function',
                'args':[repr(namespace.keys())]}
         d = self.executeAndRaise(msg, self.shell.push_function, namespace)
         return d
     
     def pull_function(self, keys):
         msg = {'engineid':self.id,
                'method':'pull_function',
                'args':[repr(keys)]}
         d = self.executeAndRaise(msg, self.shell.pull_function, keys)
         return d
     
     def get_result(self, i=None):
         msg = {'engineid':self.id,
                'method':'get_result',
                'args':[repr(i)]}
         d = self.executeAndRaise(msg, self.shell.getCommand, i)
         d.addCallback(self.addIDToResult)
         return d
     
     def reset(self):
         msg = {'engineid':self.id,
                'method':'reset',
                'args':[]}
         del self.shell
         self.shell = self.shellClass()
         self.properties.clear()
         d = self.executeAndRaise(msg, self._seedNamespace)
         return d
     
     def kill(self):
         drop_engine(self.id)
         try:
             reactor.stop()
         except RuntimeError:
             log.msg('The reactor was not running apparently.')
             return defer.fail()
         else:
             return defer.succeed(None)
     
     def keys(self):
         """Return a list of variables names in the users top level namespace.
         
         This used to return a dict of all the keys/repr(values) in the 
         user's namespace.  This was too much info for the ControllerService
         to handle so it is now just a list of keys.
         """
         
         remotes = []
         for k in self.shell.user_ns.iterkeys():
             if k not in ['__name__', '_ih', '_oh', '__builtins__',
                          'In', 'Out', '_', '__', '___', '__IP', 'input', 'raw_input']:
                 remotes.append(k)
         return defer.succeed(remotes)
     
     def set_properties(self, properties):
         msg = {'engineid':self.id,
                'method':'set_properties',
                'args':[repr(properties.keys())]}
         return self.executeAndRaise(msg, self.properties.update, properties)
     
     def get_properties(self, keys=None):
         msg = {'engineid':self.id,
                'method':'get_properties',
                'args':[repr(keys)]}
         if keys is None:
             keys = self.properties.keys()
         return self.executeAndRaise(msg, self.properties.subDict, *keys)
     
     def _doDel(self, keys):
         for key in keys:
             del self.properties[key]
     
     def del_properties(self, keys):
         msg = {'engineid':self.id,
                'method':'del_properties',
                'args':[repr(keys)]}
         return self.executeAndRaise(msg, self._doDel, keys)
     
     def _doHas(self, keys):
         return [self.properties.has_key(key) for key in keys]
     
     def has_properties(self, keys):
         msg = {'engineid':self.id,
                'method':'has_properties',
                'args':[repr(keys)]}
         return self.executeAndRaise(msg, self._doHas, keys)
     
     def clear_properties(self):
         msg = {'engineid':self.id,
                'method':'clear_properties',
                'args':[]}
         return self.executeAndRaise(msg, self.properties.clear)
     
     def push_serialized(self, sNamespace):
         msg = {'engineid':self.id,
                'method':'push_serialized',
                'args':[repr(sNamespace.keys())]}       
         ns = {}
         for k,v in sNamespace.iteritems():
             try:
                 unserialized = newserialized.IUnSerialized(v)
                 ns[k] = unserialized.getObject()
             except:
                 return defer.fail()
         return self.executeAndRaise(msg, self.shell.push, ns)
     
     def pull_serialized(self, keys):
         msg = {'engineid':self.id,
                'method':'pull_serialized',
                'args':[repr(keys)]}
         if isinstance(keys, str):
             keys = [keys]
         if len(keys)==1:
             d = self.executeAndRaise(msg, self.shell.pull, keys)
             d.addCallback(newserialized.serialize)
             return d
         elif len(keys)>1:
             d = self.executeAndRaise(msg, self.shell.pull, keys)         
             @d.addCallback
             def packThemUp(values):
                 serials = []
                 for v in values:
                     try:
                         serials.append(newserialized.serialize(v))
                     except:
                         return defer.fail(failure.Failure())
                 return serials
             return packThemUp
 
 
 def queue(methodToQueue):
     def queuedMethod(this, *args, **kwargs):
         name = methodToQueue.__name__
         return this.submitCommand(Command(name, *args, **kwargs))
     return queuedMethod
     
 class QueuedEngine(object):
     """Adapt an IEngineBase to an IEngineQueued by wrapping it.
     
     The resulting object will implement IEngineQueued which extends
     IEngineCore which extends (IEngineBase, IEngineSerialized). 
     
     This seems like the best way of handling it, but I am not sure.  The
     other option is to have the various base interfaces be used like
     mix-in intefaces.  The problem I have with this is adpatation is
     more difficult and complicated because there can be can multiple
     original and final Interfaces. 
     """
     
     zi.implements(IEngineQueued)
     
     def __init__(self, engine):
         """Create a QueuedEngine object from an engine
         
         engine:       An implementor of IEngineCore and IEngineSerialized
         keepUpToDate: whether to update the remote status when the 
                       queue is empty.  Defaults to False.
         """
         
         # This is the right way to do these tests rather than 
         # IEngineCore in list(zi.providedBy(engine)) which will only 
         # picks of the interfaces that are directly declared by engine.
         assert IEngineBase.providedBy(engine), \
             "engine passed to QueuedEngine doesn't provide IEngineBase"
             
         self.engine = engine
         self.id = engine.id
         self.queued = []
         self.history = {}
         self.engineStatus = {}
         self.currentCommand = None
         self.failureObservers = []
     
     def _get_properties(self):
         return self.engine.properties
     
     properties = property(_get_properties, lambda self, _: None)
     # Queue management methods.  You should not call these directly
     
     def submitCommand(self, cmd):
         """Submit command to queue."""
         
         d = defer.Deferred()
         cmd.setDeferred(d)
         if self.currentCommand is not None:
             if self.currentCommand.finished:
                 # log.msg("Running command immediately: %r" % cmd)
                 self.currentCommand = cmd
                 self.runCurrentCommand()
             else:  # command is still running  
                 # log.msg("Command is running: %r" % self.currentCommand)
                 # log.msg("Queueing: %r" % cmd)
                 self.queued.append(cmd)
         else:
             # log.msg("No current commands, running: %r" % cmd)
             self.currentCommand = cmd
             self.runCurrentCommand()
         return d
     
     def runCurrentCommand(self):
         """Run current command."""
         
         cmd = self.currentCommand
         f = getattr(self.engine, cmd.remoteMethod, None)
         if f:
             d = f(*cmd.args, **cmd.kwargs)
             if cmd.remoteMethod is 'execute':
                 d.addCallback(self.saveResult)
             d.addCallback(self.finishCommand)
             d.addErrback(self.abortCommand)
         else:
             return defer.fail(AttributeError(cmd.remoteMethod))
     
     def _flushQueue(self):
         """Pop next command in queue and run it."""
         
         if len(self.queued) > 0:
             self.currentCommand = self.queued.pop(0)
             self.runCurrentCommand()
     
     def saveResult(self, result):
         """Put the result in the history."""
         self.history[result['number']] = result
         return result
     
     def finishCommand(self, result):
         """Finish currrent command."""
         
         # The order of these commands is absolutely critical.
         self.currentCommand.handleResult(result)
         self.currentCommand.finished = True
         self._flushQueue()
         return result
     
     def abortCommand(self, reason):
         """Abort current command.
         
         This eats the Failure but first passes it onto the Deferred that the 
         user has.
         
         It also clear out the queue so subsequence commands don't run.
         """
 
         # The order of these 3 commands is absolutely critical.  The currentCommand
         # must first be marked as finished BEFORE the queue is cleared and before
         # the current command is sent the failure.
         # Also, the queue must be cleared BEFORE the current command is sent the Failure
         # otherwise the errback chain could trigger new commands to be added to the 
         # queue before we clear it.  We should clear ONLY the commands that were in
         # the queue when the error occured. 
         self.currentCommand.finished = True
         s = "%r %r %r" % (self.currentCommand.remoteMethod, self.currentCommand.args, self.currentCommand.kwargs)
         self.clear_queue(msg=s)
         self.currentCommand.handleError(reason)
         
         return None
     
     #---------------------------------------------------------------------------
     # IEngineCore methods
     #---------------------------------------------------------------------------
     
     @queue
     def execute(self, lines):
         pass
-
+    
     @queue
     def push(self, namespace):
         pass      
     
     @queue
     def pull(self, keys):
         pass
         
     @queue
     def push_function(self, namespace):
         pass      
     
     @queue
     def pull_function(self, keys):
         pass        
 
     def get_result(self, i=None):
         if i is None:
             i = max(self.history.keys()+[None])
 
         cmd = self.history.get(i, None)
         # Uncomment this line to disable chaching of results
         #cmd = None
         if cmd is None:
             return self.submitCommand(Command('get_result', i))
         else:
             return defer.succeed(cmd)
         
     def reset(self):
         self.clear_queue()
         self.history = {}  # reset the cache - I am not sure we should do this
         return self.submitCommand(Command('reset'))
     
     def kill(self):
         self.clear_queue()
         return self.submitCommand(Command('kill'))
     
     @queue
     def keys(self):
         pass
     
     #---------------------------------------------------------------------------
     # IEngineSerialized methods
     #---------------------------------------------------------------------------
 
     @queue
     def push_serialized(self, namespace):
         pass
         
     @queue
     def pull_serialized(self, keys):
         pass
     
     #---------------------------------------------------------------------------
     # IEngineProperties methods
     #---------------------------------------------------------------------------
 
     @queue
     def set_properties(self, namespace):
         pass
         
     @queue
     def get_properties(self, keys=None):
         pass
     
     @queue
     def del_properties(self, keys):
         pass
     
     @queue
     def has_properties(self, keys):
         pass
     
     @queue
     def clear_properties(self):
         pass
     
     #---------------------------------------------------------------------------
     # IQueuedEngine methods
     #---------------------------------------------------------------------------
     
     def clear_queue(self, msg=''):
         """Clear the queue, but doesn't cancel the currently running commmand."""
         
         for cmd in self.queued:
             cmd.deferred.errback(failure.Failure(error.QueueCleared(msg)))
         self.queued = []
         return defer.succeed(None)
     
     def queue_status(self):
         if self.currentCommand is not None:
             if self.currentCommand.finished:
                 pending = repr(None)
             else:
                 pending = repr(self.currentCommand)
         else:
             pending = repr(None)
         dikt = {'queue':map(repr,self.queued), 'pending':pending}
         return defer.succeed(dikt)
         
     def register_failure_observer(self, obs):
         self.failureObservers.append(obs)
     
     def unregister_failure_observer(self, obs):
         self.failureObservers.remove(obs)
     
 
 # Now register QueuedEngine as an adpater class that makes an IEngineBase into a
 # IEngineQueued.  
 components.registerAdapter(QueuedEngine, IEngineBase, IEngineQueued)
     
 
 class Command(object):
     """A command object that encapslates queued commands.
     
     This class basically keeps track of a command that has been queued
     in a QueuedEngine.  It manages the deferreds and hold the method to be called
     and the arguments to that method.
     """
     
     
     def __init__(self, remoteMethod, *args, **kwargs):
         """Build a new Command object."""
         
         self.remoteMethod = remoteMethod
         self.args = args
         self.kwargs = kwargs
         self.finished = False
     
     def setDeferred(self, d):
         """Sets the deferred attribute of the Command."""  
           
         self.deferred = d
     
     def __repr__(self):
         if not self.args:
             args = ''
         else:
             args = str(self.args)[1:-2]  #cut off (...,)
         for k,v in self.kwargs.iteritems():
             if args:
                 args += ', '
             args += '%s=%r' %(k,v)
         return "%s(%s)" %(self.remoteMethod, args)
     
     def handleResult(self, result):
         """When the result is ready, relay it to self.deferred."""
         
         self.deferred.callback(result)
     
     def handleError(self, reason):
         """When an error has occured, relay it to self.deferred."""
         
         self.deferred.errback(reason)
 
 class ThreadedEngineService(EngineService):
     """An EngineService subclass that defers execute commands to a separate 
     thread.
     
     ThreadedEngineService uses twisted.internet.threads.deferToThread to 
     defer execute requests to a separate thread. GUI frontends may want to 
     use ThreadedEngineService as the engine in an 
     IPython.frontend.frontendbase.FrontEndBase subclass to prevent
     block execution from blocking the GUI thread.
     """
     
     zi.implements(IEngineBase)
 
     def __init__(self, shellClass=Interpreter, mpi=None):
         EngineService.__init__(self, shellClass, mpi)
     
     def wrapped_execute(self, msg, lines):
         """Wrap self.shell.execute to add extra information to tracebacks"""
         
         try:
             result = self.shell.execute(lines)
         except Exception,e:
             # This gives the following:
             # et=exception class
             # ev=exception class instance
             # tb=traceback object
             et,ev,tb = sys.exc_info()
             # This call adds attributes to the exception value
             et,ev,tb = self.shell.formatTraceback(et,ev,tb,msg)
             # Add another attribute
             
             # Create a new exception with the new attributes
             e = et(ev._ipython_traceback_text)
             e._ipython_engine_info = msg
             
             # Re-raise
             raise e
         
         return result
     
     
     def execute(self, lines):
         # Only import this if we are going to use this class
         from twisted.internet import threads
         
         msg = {'engineid':self.id,
                'method':'execute',
                'args':[lines]}
         
         d = threads.deferToThread(self.wrapped_execute, msg, lines)
         d.addCallback(self.addIDToResult)
         return d

IPython/kernel/multienginefc.py

@@ -1,757 +1,757 b''
 # encoding: utf-8
 
 """
 Expose the multiengine controller over the Foolscap network protocol.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 
 import cPickle as pickle
 from types import FunctionType
 
 from zope.interface import Interface, implements
 from twisted.internet import defer
 from twisted.python import components, failure, log
 
 from foolscap import Referenceable
 
 from IPython.kernel import error 
 from IPython.kernel.util import printer
 from IPython.kernel import map as Map
 from IPython.kernel.parallelfunction import ParallelFunction
 from IPython.kernel.mapper import (
     MultiEngineMapper, 
     IMultiEngineMapperFactory,
     IMapper
 )
 from IPython.kernel.twistedutil import gatherBoth
 from IPython.kernel.multiengine import (MultiEngine,
     IMultiEngine,
     IFullSynchronousMultiEngine,
     ISynchronousMultiEngine)
 from IPython.kernel.multiengineclient import wrapResultList
 from IPython.kernel.pendingdeferred import PendingDeferredManager
 from IPython.kernel.pickleutil import (can, canDict,
     canSequence, uncan, uncanDict, uncanSequence)
 
 from IPython.kernel.clientinterfaces import (
     IFCClientInterfaceProvider, 
     IBlockingClientAdaptor
 )
 
 # Needed to access the true globals from __main__.__dict__ 
 import __main__
 
 #-------------------------------------------------------------------------------
 # The Controller side of things
 #-------------------------------------------------------------------------------
 
 def packageResult(wrappedMethod):
     
     def wrappedPackageResult(self, *args, **kwargs):
         d = wrappedMethod(self, *args, **kwargs)
         d.addCallback(self.packageSuccess)
         d.addErrback(self.packageFailure)
         return d
     return wrappedPackageResult
 
 
 class IFCSynchronousMultiEngine(Interface):
     """Foolscap interface to `ISynchronousMultiEngine`.  
     
     The methods in this interface are similar to those of 
     `ISynchronousMultiEngine`, but their arguments and return values are pickled
     if they are not already simple Python types that can be send over XML-RPC.
     
     See the documentation of `ISynchronousMultiEngine` and `IMultiEngine` for 
     documentation about the methods.
     
     Most methods in this interface act like the `ISynchronousMultiEngine`
     versions and can be called in blocking or non-blocking mode.
     """
     pass
 
 
 class FCSynchronousMultiEngineFromMultiEngine(Referenceable):
     """Adapt `IMultiEngine` -> `ISynchronousMultiEngine` -> `IFCSynchronousMultiEngine`.
     """
     
     implements(IFCSynchronousMultiEngine, IFCClientInterfaceProvider)
     
     addSlash = True
     
     def __init__(self, multiengine):
         # Adapt the raw multiengine to `ISynchronousMultiEngine` before saving
         # it.  This allow this class to do two adaptation steps.
         self.smultiengine = ISynchronousMultiEngine(multiengine)
         self._deferredIDCallbacks = {}
     
     #---------------------------------------------------------------------------
     # Non interface methods
     #---------------------------------------------------------------------------
     
     def packageFailure(self, f):
         f.cleanFailure()
         return self.packageSuccess(f)
     
     def packageSuccess(self, obj):
         serial = pickle.dumps(obj, 2)
         return serial
     
     #---------------------------------------------------------------------------
     # Things related to PendingDeferredManager
     #---------------------------------------------------------------------------
     
     @packageResult
     def remote_get_pending_deferred(self, deferredID, block):
         d = self.smultiengine.get_pending_deferred(deferredID, block)
         try:
             callback = self._deferredIDCallbacks.pop(deferredID)
         except KeyError:
             callback = None
         if callback is not None:
             d.addCallback(callback[0], *callback[1], **callback[2])
         return d
        
     @packageResult
     def remote_clear_pending_deferreds(self):
         return defer.maybeDeferred(self.smultiengine.clear_pending_deferreds)
     
     def _addDeferredIDCallback(self, did, callback, *args, **kwargs):
         self._deferredIDCallbacks[did] = (callback, args, kwargs)
         return did
-        
+    
     #---------------------------------------------------------------------------
     # IEngineMultiplexer related methods
     #---------------------------------------------------------------------------
     
     @packageResult
     def remote_execute(self, lines, targets, block):
         return self.smultiengine.execute(lines, targets=targets, block=block)
     
     @packageResult    
     def remote_push(self, binaryNS, targets, block):
         try:
             namespace = pickle.loads(binaryNS)
         except:
             d = defer.fail(failure.Failure())
         else:
             d = self.smultiengine.push(namespace, targets=targets, block=block)
         return d
     
     @packageResult
     def remote_pull(self, keys, targets, block):
         d = self.smultiengine.pull(keys, targets=targets, block=block)
         return d
     
     @packageResult    
     def remote_push_function(self, binaryNS, targets, block):
         try:
             namespace = pickle.loads(binaryNS)
         except:
             d = defer.fail(failure.Failure())
         else:
             namespace = uncanDict(namespace)
             d = self.smultiengine.push_function(namespace, targets=targets, block=block)
         return d
     
     def _canMultipleKeys(self, result):
         return [canSequence(r) for r in result]
     
     @packageResult
     def remote_pull_function(self, keys, targets, block):
         def can_functions(r, keys):
             if len(keys)==1 or isinstance(keys, str):
                 result = canSequence(r)
             elif len(keys)>1:
                 result = [canSequence(s) for s in r]
             return result
         d = self.smultiengine.pull_function(keys, targets=targets, block=block)
         if block:
             d.addCallback(can_functions, keys)
         else:
             d.addCallback(lambda did: self._addDeferredIDCallback(did, can_functions, keys))
         return d
     
     @packageResult    
     def remote_push_serialized(self, binaryNS, targets, block):
         try:
             namespace = pickle.loads(binaryNS)
         except:
             d = defer.fail(failure.Failure())
         else:
             d = self.smultiengine.push_serialized(namespace, targets=targets, block=block)
         return d
     
     @packageResult
     def remote_pull_serialized(self, keys, targets, block):
         d = self.smultiengine.pull_serialized(keys, targets=targets, block=block)
         return d
     
     @packageResult
     def remote_get_result(self, i, targets, block):
         if i == 'None':
             i = None
         return self.smultiengine.get_result(i, targets=targets, block=block)
     
     @packageResult
     def remote_reset(self, targets, block):
         return self.smultiengine.reset(targets=targets, block=block)
     
     @packageResult
     def remote_keys(self, targets, block):
         return self.smultiengine.keys(targets=targets, block=block)
     
     @packageResult
     def remote_kill(self, controller, targets, block):
         return self.smultiengine.kill(controller, targets=targets, block=block)
     
     @packageResult
     def remote_clear_queue(self, targets, block):
         return self.smultiengine.clear_queue(targets=targets, block=block)
     
     @packageResult
     def remote_queue_status(self, targets, block):
         return self.smultiengine.queue_status(targets=targets, block=block)
     
     @packageResult
     def remote_set_properties(self, binaryNS, targets, block):
         try:
             ns = pickle.loads(binaryNS)
         except:
             d = defer.fail(failure.Failure())
         else:
             d = self.smultiengine.set_properties(ns, targets=targets, block=block)
         return d
     
     @packageResult
     def remote_get_properties(self, keys, targets, block):
         if keys=='None':
             keys=None
         return self.smultiengine.get_properties(keys, targets=targets, block=block)
     
     @packageResult
     def remote_has_properties(self, keys, targets, block):
         return self.smultiengine.has_properties(keys, targets=targets, block=block)
     
     @packageResult
     def remote_del_properties(self, keys, targets, block):
         return self.smultiengine.del_properties(keys, targets=targets, block=block)
     
     @packageResult
     def remote_clear_properties(self, targets, block):
         return self.smultiengine.clear_properties(targets=targets, block=block)
     
     #---------------------------------------------------------------------------
     # IMultiEngine related methods
     #---------------------------------------------------------------------------
     
     def remote_get_ids(self):
         """Get the ids of the registered engines.
         
         This method always blocks.
         """
         return self.smultiengine.get_ids()
     
     #---------------------------------------------------------------------------
     # IFCClientInterfaceProvider related methods
     #---------------------------------------------------------------------------
     
     def remote_get_client_name(self):
         return 'IPython.kernel.multienginefc.FCFullSynchronousMultiEngineClient'
 
 
 # The __init__ method of `FCMultiEngineFromMultiEngine` first adapts the
 # `IMultiEngine` to `ISynchronousMultiEngine` so this is actually doing a
 # two phase adaptation.
 components.registerAdapter(FCSynchronousMultiEngineFromMultiEngine,
             IMultiEngine, IFCSynchronousMultiEngine)
 
 
 #-------------------------------------------------------------------------------
 # The Client side of things
 #-------------------------------------------------------------------------------
 
 
 class FCFullSynchronousMultiEngineClient(object):
     
     implements(
         IFullSynchronousMultiEngine, 
         IBlockingClientAdaptor,
         IMultiEngineMapperFactory,
         IMapper
     )
     
     def __init__(self, remote_reference):
         self.remote_reference = remote_reference
         self._deferredIDCallbacks = {}
         # This class manages some pending deferreds through this instance.  This
         # is required for methods like gather/scatter as it enables us to
         # create our own pending deferreds for composite operations.
         self.pdm = PendingDeferredManager()
     
     #---------------------------------------------------------------------------
     # Non interface methods
     #---------------------------------------------------------------------------
                  
     def unpackage(self, r):
         return pickle.loads(r)
     
     #---------------------------------------------------------------------------
     # Things related to PendingDeferredManager
     #---------------------------------------------------------------------------
     
     def get_pending_deferred(self, deferredID, block=True):
         
         # Because we are managing some pending deferreds locally (through
         # self.pdm) and some remotely (on the controller), we first try the 
         # local one and then the remote one.
         if self.pdm.quick_has_id(deferredID):
             d = self.pdm.get_pending_deferred(deferredID, block)
             return d
         else:
             d = self.remote_reference.callRemote('get_pending_deferred', deferredID, block)
             d.addCallback(self.unpackage)
             try:
                 callback = self._deferredIDCallbacks.pop(deferredID)
             except KeyError:
                 callback = None
             if callback is not None:
                 d.addCallback(callback[0], *callback[1], **callback[2])
             return d
     
     def clear_pending_deferreds(self):
         
         # This clear both the local (self.pdm) and remote pending deferreds
         self.pdm.clear_pending_deferreds()
         d2 = self.remote_reference.callRemote('clear_pending_deferreds')
         d2.addCallback(self.unpackage)
         return d2
     
     def _addDeferredIDCallback(self, did, callback, *args, **kwargs):
         self._deferredIDCallbacks[did] = (callback, args, kwargs)
         return did
        
     #---------------------------------------------------------------------------
     # IEngineMultiplexer related methods
     #---------------------------------------------------------------------------
-        
+    
     def execute(self, lines, targets='all', block=True):
         d = self.remote_reference.callRemote('execute', lines, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def push(self, namespace, targets='all', block=True):
         serial = pickle.dumps(namespace, 2)
         d =  self.remote_reference.callRemote('push', serial, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def pull(self, keys, targets='all', block=True):
         d = self.remote_reference.callRemote('pull', keys, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def push_function(self, namespace, targets='all', block=True):
         cannedNamespace = canDict(namespace)
         serial = pickle.dumps(cannedNamespace, 2)
         d = self.remote_reference.callRemote('push_function', serial, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def pull_function(self, keys, targets='all', block=True):
         def uncan_functions(r, keys):
             if len(keys)==1 or isinstance(keys, str):
                 return uncanSequence(r)
             elif len(keys)>1:
                 return [uncanSequence(s) for s in r]
         d = self.remote_reference.callRemote('pull_function', keys, targets, block)
         if block:
             d.addCallback(self.unpackage)
             d.addCallback(uncan_functions, keys)
         else:
             d.addCallback(self.unpackage)
             d.addCallback(lambda did: self._addDeferredIDCallback(did, uncan_functions, keys))
         return d
     
     def push_serialized(self, namespace, targets='all', block=True):
         cannedNamespace = canDict(namespace)
         serial = pickle.dumps(cannedNamespace, 2)
         d =  self.remote_reference.callRemote('push_serialized', serial, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def pull_serialized(self, keys, targets='all', block=True):
         d = self.remote_reference.callRemote('pull_serialized', keys, targets, block)
         d.addCallback(self.unpackage)
         return d
         
     def get_result(self, i=None, targets='all', block=True):
         if i is None: # This is because None cannot be marshalled by xml-rpc
             i = 'None'
         d = self.remote_reference.callRemote('get_result', i, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def reset(self, targets='all', block=True):
         d = self.remote_reference.callRemote('reset', targets, block)
         d.addCallback(self.unpackage)
         return d        
     
     def keys(self, targets='all', block=True):
         d = self.remote_reference.callRemote('keys', targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def kill(self, controller=False, targets='all', block=True):
         d = self.remote_reference.callRemote('kill', controller, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def clear_queue(self, targets='all', block=True):
         d = self.remote_reference.callRemote('clear_queue', targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def queue_status(self, targets='all', block=True):
         d = self.remote_reference.callRemote('queue_status', targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def set_properties(self, properties, targets='all', block=True):
         serial = pickle.dumps(properties, 2)
         d = self.remote_reference.callRemote('set_properties', serial, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def get_properties(self, keys=None, targets='all', block=True):
         if keys==None:
             keys='None'
         d = self.remote_reference.callRemote('get_properties', keys, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def has_properties(self, keys, targets='all', block=True):
         d = self.remote_reference.callRemote('has_properties', keys, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def del_properties(self, keys, targets='all', block=True):
         d = self.remote_reference.callRemote('del_properties', keys, targets, block)
         d.addCallback(self.unpackage)
         return d
     
     def clear_properties(self, targets='all', block=True):
         d = self.remote_reference.callRemote('clear_properties', targets, block)
         d.addCallback(self.unpackage)
         return d
     
     #---------------------------------------------------------------------------
     # IMultiEngine related methods
     #---------------------------------------------------------------------------
     
     def get_ids(self):
         d = self.remote_reference.callRemote('get_ids')
         return d
     
     #---------------------------------------------------------------------------
     # ISynchronousMultiEngineCoordinator related methods
     #---------------------------------------------------------------------------
 
     def _process_targets(self, targets):
         def create_targets(ids):
             if isinstance(targets, int):
                 engines = [targets]
             elif targets=='all':
                 engines = ids
             elif isinstance(targets, (list, tuple)):
                 engines = targets
             for t in engines:
                 if not t in ids:
                     raise error.InvalidEngineID("engine with id %r does not exist"%t)
             return engines
         
         d = self.get_ids()
         d.addCallback(create_targets)
         return d
     
     def scatter(self, key, seq, dist='b', flatten=False, targets='all', block=True):
         
         # Note: scatter and gather handle pending deferreds locally through self.pdm.
         # This enables us to collect a bunch fo deferred ids and make a secondary 
         # deferred id that corresponds to the entire group.  This logic is extremely
         # difficult to get right though.
         def do_scatter(engines):
             nEngines = len(engines)
             mapClass = Map.dists[dist]
             mapObject = mapClass()
             d_list = []
             # Loop through and push to each engine in non-blocking mode.
             # This returns a set of deferreds to deferred_ids
             for index, engineid in enumerate(engines):
                 partition = mapObject.getPartition(seq, index, nEngines)
                 if flatten and len(partition) == 1:
                     d = self.push({key: partition[0]}, targets=engineid, block=False)
                 else:
                     d = self.push({key: partition}, targets=engineid, block=False)
                 d_list.append(d)
             # Collect the deferred to deferred_ids
             d = gatherBoth(d_list,
                            fireOnOneErrback=0,
                            consumeErrors=1,
                            logErrors=0)
             # Now d has a list of deferred_ids or Failures coming
             d.addCallback(error.collect_exceptions, 'scatter')
             def process_did_list(did_list):
                 """Turn a list of deferred_ids into a final result or failure."""
                 new_d_list = [self.get_pending_deferred(did, True) for did in did_list]
                 final_d = gatherBoth(new_d_list,
                                      fireOnOneErrback=0,
                                      consumeErrors=1,
                                      logErrors=0)
                 final_d.addCallback(error.collect_exceptions, 'scatter')
                 final_d.addCallback(lambda lop: [i[0] for i in lop])
                 return final_d
             # Now, depending on block, we need to handle the list deferred_ids
             # coming down the pipe diferently.
             if block:
                 # If we are blocking register a callback that will transform the
                 # list of deferred_ids into the final result.
                 d.addCallback(process_did_list)
                 return d
             else:
                 # Here we are going to use a _local_ PendingDeferredManager.
                 deferred_id = self.pdm.get_deferred_id()
                 # This is the deferred we will return to the user that will fire
                 # with the local deferred_id AFTER we have received the list of 
                 # primary deferred_ids
                 d_to_return = defer.Deferred()
                 def do_it(did_list):
                     """Produce a deferred to the final result, but first fire the
                     deferred we will return to the user that has the local
                     deferred id."""
                     d_to_return.callback(deferred_id)
                     return process_did_list(did_list)
                 d.addCallback(do_it)
                 # Now save the deferred to the final result
                 self.pdm.save_pending_deferred(d, deferred_id)
                 return d_to_return
 
         d = self._process_targets(targets)
         d.addCallback(do_scatter)
         return d
 
     def gather(self, key, dist='b', targets='all', block=True):
         
         # Note: scatter and gather handle pending deferreds locally through self.pdm.
         # This enables us to collect a bunch fo deferred ids and make a secondary 
         # deferred id that corresponds to the entire group.  This logic is extremely
         # difficult to get right though.
         def do_gather(engines):
             nEngines = len(engines)
             mapClass = Map.dists[dist]
             mapObject = mapClass()
             d_list = []
             # Loop through and push to each engine in non-blocking mode.
             # This returns a set of deferreds to deferred_ids
             for index, engineid in enumerate(engines):
                 d = self.pull(key, targets=engineid, block=False)
                 d_list.append(d)
             # Collect the deferred to deferred_ids
             d = gatherBoth(d_list,
                            fireOnOneErrback=0,
                            consumeErrors=1,
                            logErrors=0)
             # Now d has a list of deferred_ids or Failures coming
             d.addCallback(error.collect_exceptions, 'scatter')
             def process_did_list(did_list):
                 """Turn a list of deferred_ids into a final result or failure."""
                 new_d_list = [self.get_pending_deferred(did, True) for did in did_list]
                 final_d = gatherBoth(new_d_list,
                                      fireOnOneErrback=0,
                                      consumeErrors=1,
                                      logErrors=0)
                 final_d.addCallback(error.collect_exceptions, 'gather')
                 final_d.addCallback(lambda lop: [i[0] for i in lop])
                 final_d.addCallback(mapObject.joinPartitions)
                 return final_d
             # Now, depending on block, we need to handle the list deferred_ids
             # coming down the pipe diferently.
             if block:
                 # If we are blocking register a callback that will transform the
                 # list of deferred_ids into the final result.
                 d.addCallback(process_did_list)
                 return d
             else:
                 # Here we are going to use a _local_ PendingDeferredManager.
                 deferred_id = self.pdm.get_deferred_id()
                 # This is the deferred we will return to the user that will fire
                 # with the local deferred_id AFTER we have received the list of 
                 # primary deferred_ids
                 d_to_return = defer.Deferred()
                 def do_it(did_list):
                     """Produce a deferred to the final result, but first fire the
                     deferred we will return to the user that has the local
                     deferred id."""
                     d_to_return.callback(deferred_id)
                     return process_did_list(did_list)
                 d.addCallback(do_it)
                 # Now save the deferred to the final result
                 self.pdm.save_pending_deferred(d, deferred_id)
                 return d_to_return
 
         d = self._process_targets(targets)
         d.addCallback(do_gather)
         return d
 
     def raw_map(self, func, sequences, dist='b', targets='all', block=True):
         """
         A parallelized version of Python's builtin map.
         
         This has a slightly different syntax than the builtin `map`.
         This is needed because we need to have keyword arguments and thus
         can't use *args to capture all the sequences.  Instead, they must
         be passed in a list or tuple.
         
         raw_map(func, seqs) -> map(func, seqs[0], seqs[1], ...)
         
         Most users will want to use parallel functions or the `mapper`
         and `map` methods for an API that follows that of the builtin
         `map`.
         """
         if not isinstance(sequences, (list, tuple)):
             raise TypeError('sequences must be a list or tuple')
         max_len = max(len(s) for s in sequences)
         for s in sequences:
             if len(s)!=max_len:
                 raise ValueError('all sequences must have equal length')
         if isinstance(func, FunctionType):
             d = self.push_function(dict(_ipython_map_func=func), targets=targets, block=False)
             d.addCallback(lambda did: self.get_pending_deferred(did, True))
             sourceToRun = '_ipython_map_seq_result = map(_ipython_map_func, *zip(*_ipython_map_seq))'
         elif isinstance(func, str):
             d = defer.succeed(None)
             sourceToRun = \
                 '_ipython_map_seq_result = map(%s, *zip(*_ipython_map_seq))' % func
         else:
             raise TypeError("func must be a function or str")
         
         d.addCallback(lambda _: self.scatter('_ipython_map_seq', zip(*sequences), dist, targets=targets))
         d.addCallback(lambda _: self.execute(sourceToRun, targets=targets, block=False))
         d.addCallback(lambda did: self.get_pending_deferred(did, True))
         d.addCallback(lambda _: self.gather('_ipython_map_seq_result', dist, targets=targets, block=block))
         return d
 
     def map(self, func, *sequences):
         """
         A parallel version of Python's builtin `map` function.
         
         This method applies a function to sequences of arguments.  It 
         follows the same syntax as the builtin `map`.
         
         This method creates a mapper objects by calling `self.mapper` with
         no arguments and then uses that mapper to do the mapping.  See
         the documentation of `mapper` for more details.
         """
         return self.mapper().map(func, *sequences)
     
     def mapper(self, dist='b', targets='all', block=True):
         """
         Create a mapper object that has a `map` method.
         
         This method returns an object that implements the `IMapper` 
         interface.  This method is a factory that is used to control how 
         the map happens.
         
         :Parameters:
             dist : str
                 What decomposition to use, 'b' is the only one supported
                 currently
             targets : str, int, sequence of ints
                 Which engines to use for the map
             block : boolean
                 Should calls to `map` block or not
         """
         return MultiEngineMapper(self, dist, targets, block)
 
     def parallel(self, dist='b', targets='all', block=True):
         """
         A decorator that turns a function into a parallel function.
         
         This can be used as:
         
         @parallel()
         def f(x, y)
             ...
         
         f(range(10), range(10))
         
         This causes f(0,0), f(1,1), ... to be called in parallel.
         
         :Parameters:
             dist : str
                 What decomposition to use, 'b' is the only one supported
                 currently
             targets : str, int, sequence of ints
                 Which engines to use for the map
             block : boolean
                 Should calls to `map` block or not
         """
         mapper = self.mapper(dist, targets, block)
         pf = ParallelFunction(mapper)
         return pf
     
     #---------------------------------------------------------------------------
     # ISynchronousMultiEngineExtras related methods
     #---------------------------------------------------------------------------
     
     def _transformPullResult(self, pushResult, multitargets, lenKeys):
         if not multitargets:
             result = pushResult[0]
         elif lenKeys > 1:
             result = zip(*pushResult)
         elif lenKeys is 1:
             result = list(pushResult)
         return result
     
     def zip_pull(self, keys, targets='all', block=True):
         multitargets = not isinstance(targets, int) and len(targets) > 1
         lenKeys = len(keys)
         d = self.pull(keys, targets=targets, block=block)
         if block:
             d.addCallback(self._transformPullResult, multitargets, lenKeys)
         else:
             d.addCallback(lambda did: self._addDeferredIDCallback(did, self._transformPullResult, multitargets, lenKeys))
         return d
     
     def run(self, fname, targets='all', block=True):
         fileobj = open(fname,'r')
         source = fileobj.read()
         fileobj.close()
         # if the compilation blows, we get a local error right away
         try:
             code = compile(source,fname,'exec')
         except:
             return defer.fail(failure.Failure()) 
         # Now run the code
         d = self.execute(source, targets=targets, block=block)
         return d
     
     #---------------------------------------------------------------------------
     # IBlockingClientAdaptor related methods
     #---------------------------------------------------------------------------
     
     def adapt_to_blocking_client(self):
         from IPython.kernel.multiengineclient import IFullBlockingMultiEngineClient
         return IFullBlockingMultiEngineClient(self)

IPython/kernel/scripts/ipcluster.py

@@ -1,521 +1,723 b''
 #!/usr/bin/env python
 # encoding: utf-8
 
 """Start an IPython cluster = (controller + engines)."""
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import re
 import sys
 import signal
+import tempfile
 pjoin = os.path.join
 
 from twisted.internet import reactor, defer
 from twisted.internet.protocol import ProcessProtocol
 from twisted.internet.error import ProcessDone, ProcessTerminated
 from twisted.internet.utils import getProcessOutput
 from twisted.python import failure, log
 
 from IPython.external import argparse
 from IPython.external import Itpl
 from IPython.genutils import get_ipython_dir, num_cpus
 from IPython.kernel.fcutil import have_crypto
 from IPython.kernel.error import SecurityError
 from IPython.kernel.fcutil import have_crypto
 from IPython.kernel.twistedutil import gatherBoth
 from IPython.kernel.util import printer
 
 
 #-----------------------------------------------------------------------------
 # General process handling code
 #-----------------------------------------------------------------------------
 
 def find_exe(cmd):
     try:
         import win32api
     except ImportError:
         raise ImportError('you need to have pywin32 installed for this to work')
     else:
         try:
             (path, offest) = win32api.SearchPath(os.environ['PATH'],cmd + '.exe')
         except:
             (path, offset) = win32api.SearchPath(os.environ['PATH'],cmd + '.bat')
     return path
 
 class ProcessStateError(Exception):
     pass
 
 class UnknownStatus(Exception):
     pass
 
 class LauncherProcessProtocol(ProcessProtocol):
     """
     A ProcessProtocol to go with the ProcessLauncher.
     """
     def __init__(self, process_launcher):
         self.process_launcher = process_launcher
     
     def connectionMade(self):
         self.process_launcher.fire_start_deferred(self.transport.pid)
     
     def processEnded(self, status):
         value = status.value
         if isinstance(value, ProcessDone):
             self.process_launcher.fire_stop_deferred(0)
         elif isinstance(value, ProcessTerminated):
             self.process_launcher.fire_stop_deferred(
                 {'exit_code':value.exitCode,
                  'signal':value.signal,
                  'status':value.status
                 }
             )
         else:
             raise UnknownStatus("unknown exit status, this is probably a bug in Twisted")
-
+    
     def outReceived(self, data):
         log.msg(data)
-
+    
     def errReceived(self, data):
         log.err(data)
 
 class ProcessLauncher(object):
     """
     Start and stop an external process in an asynchronous manner.
     
     Currently this uses deferreds to notify other parties of process state
     changes.  This is an awkward design and should be moved to using
     a formal NotificationCenter.
     """
     def __init__(self, cmd_and_args):
         self.cmd = cmd_and_args[0]
         self.args = cmd_and_args
         self._reset()
     
     def _reset(self):
         self.process_protocol = None
         self.pid = None
         self.start_deferred = None
         self.stop_deferreds = []
         self.state = 'before' # before, running, or after
     
     @property
     def running(self):
         if self.state == 'running':
             return True
         else:
             return False
     
     def fire_start_deferred(self, pid):
         self.pid = pid
         self.state = 'running'
         log.msg('Process %r has started with pid=%i' % (self.args, pid))
         self.start_deferred.callback(pid)
     
     def start(self):
         if self.state == 'before':
             self.process_protocol = LauncherProcessProtocol(self)
             self.start_deferred = defer.Deferred()
             self.process_transport = reactor.spawnProcess(
                 self.process_protocol,
                 self.cmd,
                 self.args,
                 env=os.environ
             )
             return self.start_deferred
         else:
             s = 'the process has already been started and has state: %r' % \
                 self.state
             return defer.fail(ProcessStateError(s))
     
     def get_stop_deferred(self):
         if self.state == 'running' or self.state == 'before':
             d = defer.Deferred()
             self.stop_deferreds.append(d)
             return d
         else:
             s = 'this process is already complete'
             return defer.fail(ProcessStateError(s))
     
     def fire_stop_deferred(self, exit_code):
         log.msg('Process %r has stopped with %r' % (self.args, exit_code))
         self.state = 'after'
         for d in self.stop_deferreds:
             d.callback(exit_code)
     
     def signal(self, sig):
         """
         Send a signal to the process.
         
         The argument sig can be ('KILL','INT', etc.) or any signal number.
         """
         if self.state == 'running':
             self.process_transport.signalProcess(sig)
     
     # def __del__(self):
     #     self.signal('KILL')
     
     def interrupt_then_kill(self, delay=1.0):
         self.signal('INT')
         reactor.callLater(delay, self.signal, 'KILL')
 
 
 #-----------------------------------------------------------------------------
 # Code for launching controller and engines
 #-----------------------------------------------------------------------------
 
 
 class ControllerLauncher(ProcessLauncher):
     
     def __init__(self, extra_args=None):
         if sys.platform == 'win32':
             # This logic is needed because the ipcontroller script doesn't
             # always get installed in the same way or in the same location.
             from IPython.kernel.scripts import ipcontroller
             script_location = ipcontroller.__file__.replace('.pyc', '.py')
             # The -u option here turns on unbuffered output, which is required
             # on Win32 to prevent wierd conflict and problems with Twisted
             args = [find_exe('python'), '-u', script_location]
         else:
             args = ['ipcontroller']
         self.extra_args = extra_args
         if extra_args is not None:
             args.extend(extra_args)
         
         ProcessLauncher.__init__(self, args)
 
 
 class EngineLauncher(ProcessLauncher):
     
     def __init__(self, extra_args=None):
         if sys.platform == 'win32':
             # This logic is needed because the ipcontroller script doesn't
             # always get installed in the same way or in the same location.
             from IPython.kernel.scripts import ipengine
             script_location = ipengine.__file__.replace('.pyc', '.py')
             # The -u option here turns on unbuffered output, which is required
             # on Win32 to prevent wierd conflict and problems with Twisted
             args = [find_exe('python'), '-u', script_location]
         else:
             args = ['ipengine']
         self.extra_args = extra_args
         if extra_args is not None:
             args.extend(extra_args)
         
         ProcessLauncher.__init__(self, args)
 
 
 class LocalEngineSet(object):
     
     def __init__(self, extra_args=None):
         self.extra_args = extra_args
         self.launchers = []
     
     def start(self, n):
         dlist = []
         for i in range(n):
             el = EngineLauncher(extra_args=self.extra_args)
             d = el.start()
             self.launchers.append(el)
             dlist.append(d)
         dfinal = gatherBoth(dlist, consumeErrors=True)
         dfinal.addCallback(self._handle_start)
         return dfinal
     
     def _handle_start(self, r):
         log.msg('Engines started with pids: %r' % r)
         return r
     
     def _handle_stop(self, r):
         log.msg('Engines received signal: %r' % r)
         return r
     
     def signal(self, sig):
         dlist = []
         for el in self.launchers:
             d = el.get_stop_deferred()
             dlist.append(d)
             el.signal(sig)
         dfinal = gatherBoth(dlist, consumeErrors=True)
         dfinal.addCallback(self._handle_stop)
         return dfinal
     
     def interrupt_then_kill(self, delay=1.0):
         dlist = []
         for el in self.launchers:
             d = el.get_stop_deferred()
             dlist.append(d)
             el.interrupt_then_kill(delay)
         dfinal = gatherBoth(dlist, consumeErrors=True)
         dfinal.addCallback(self._handle_stop)
         return dfinal
 
 
 class BatchEngineSet(object):
     
     # Subclasses must fill these in.  See PBSEngineSet
     submit_command = ''
     delete_command = ''
     job_id_regexp = ''
     
     def __init__(self, template_file, **kwargs):
         self.template_file = template_file
         self.context = {}
         self.context.update(kwargs)
         self.batch_file = self.template_file+'-run'
-
+    
     def parse_job_id(self, output):
         m = re.match(self.job_id_regexp, output)
         if m is not None:
             job_id = m.group()
         else:
             raise Exception("job id couldn't be determined: %s" % output)
         self.job_id = job_id
         log.msg('Job started with job id: %r' % job_id)
         return job_id
     
     def write_batch_script(self, n):
         self.context['n'] = n
         template = open(self.template_file, 'r').read()
         log.msg('Using template for batch script: %s' % self.template_file)
         script_as_string = Itpl.itplns(template, self.context)
         log.msg('Writing instantiated batch script: %s' % self.batch_file)
         f = open(self.batch_file,'w')
         f.write(script_as_string)
         f.close()
     
     def handle_error(self, f):
         f.printTraceback()
         f.raiseException()
     
     def start(self, n):
         self.write_batch_script(n)
         d = getProcessOutput(self.submit_command,
             [self.batch_file],env=os.environ)
         d.addCallback(self.parse_job_id)
         d.addErrback(self.handle_error)
         return d
     
     def kill(self):
         d = getProcessOutput(self.delete_command,
             [self.job_id],env=os.environ)
         return d
 
 class PBSEngineSet(BatchEngineSet):
     
     submit_command = 'qsub'
     delete_command = 'qdel'
     job_id_regexp = '\d+'
     
     def __init__(self, template_file, **kwargs):
         BatchEngineSet.__init__(self, template_file, **kwargs)
 
 
+sshx_template="""#!/bin/sh
+"$@" &> /dev/null &
+echo $!
+"""
+
+engine_killer_template="""#!/bin/sh
+ps -fu `whoami` | grep '[i]pengine' | awk '{print $2}' | xargs kill -TERM
+"""
+
+class SSHEngineSet(object):
+    sshx_template=sshx_template
+    engine_killer_template=engine_killer_template
+    
+    def __init__(self, engine_hosts, sshx=None, ipengine="ipengine"):
+        """Start a controller on localhost and engines using ssh.
+        
+        The engine_hosts argument is a dict with hostnames as keys and
+        the number of engine (int) as values.  sshx is the name of a local
+        file that will be used to run remote commands.  This file is used
+        to setup the environment properly.
+        """
+        
+        self.temp_dir = tempfile.gettempdir()
+        if sshx is not None:
+            self.sshx = sshx
+        else:
+            # Write the sshx.sh file locally from our template.
+            self.sshx = os.path.join(
+                self.temp_dir,
+                '%s-main-sshx.sh' % os.environ['USER']
+            )
+            f = open(self.sshx, 'w')
+            f.writelines(self.sshx_template)
+            f.close()
+        self.engine_command = ipengine
+        self.engine_hosts = engine_hosts
+        # Write the engine killer script file locally from our template.
+        self.engine_killer = os.path.join(
+            self.temp_dir,  
+            '%s-local-engine_killer.sh' % os.environ['USER']
+        )
+        f = open(self.engine_killer, 'w')
+        f.writelines(self.engine_killer_template)
+        f.close()
+    
+    def start(self, send_furl=False):
+        dlist = []
+        for host in self.engine_hosts.keys():
+            count = self.engine_hosts[host]
+            d = self._start(host, count, send_furl)
+            dlist.append(d)
+        return gatherBoth(dlist, consumeErrors=True)
+    
+    def _start(self, hostname, count=1, send_furl=False):
+        if send_furl:
+            d = self._scp_furl(hostname)
+        else:
+            d = defer.succeed(None)
+        d.addCallback(lambda r: self._scp_sshx(hostname))
+        d.addCallback(lambda r: self._ssh_engine(hostname, count))
+        return d
+        
+    def _scp_furl(self, hostname):
+        scp_cmd = "scp ~/.ipython/security/ipcontroller-engine.furl %s:.ipython/security/" % (hostname)
+        cmd_list = scp_cmd.split()
+        cmd_list[1] = os.path.expanduser(cmd_list[1])
+        log.msg('Copying furl file: %s' % scp_cmd)
+        d = getProcessOutput(cmd_list[0], cmd_list[1:], env=os.environ) 
+        return d
+    
+    def _scp_sshx(self, hostname):
+        scp_cmd = "scp %s %s:%s/%s-sshx.sh" % (
+            self.sshx, hostname, 
+            self.temp_dir, os.environ['USER']
+        )
+        print
+        log.msg("Copying sshx: %s" % scp_cmd)
+        sshx_scp = scp_cmd.split()
+        d = getProcessOutput(sshx_scp[0], sshx_scp[1:], env=os.environ)
+        return d
+    
+    def _ssh_engine(self, hostname, count):
+        exec_engine = "ssh %s sh %s/%s-sshx.sh %s" % (
+            hostname, self.temp_dir, 
+            os.environ['USER'], self.engine_command
+        )
+        cmds = exec_engine.split()
+        dlist = []
+        log.msg("about to start engines...")
+        for i in range(count):
+            log.msg('Starting engines: %s' % exec_engine)
+            d = getProcessOutput(cmds[0], cmds[1:], env=os.environ)
+            dlist.append(d)
+        return gatherBoth(dlist, consumeErrors=True)
+    
+    def kill(self):
+        dlist = []
+        for host in self.engine_hosts.keys():
+            d = self._killall(host)
+            dlist.append(d)
+        return gatherBoth(dlist, consumeErrors=True)
+    
+    def _killall(self, hostname):
+        d = self._scp_engine_killer(hostname)
+        d.addCallback(lambda r: self._ssh_kill(hostname))
+        # d.addErrback(self._exec_err)
+        return d
+
+    def _scp_engine_killer(self, hostname):
+        scp_cmd = "scp %s %s:%s/%s-engine_killer.sh" % (
+            self.engine_killer, 
+            hostname, 
+            self.temp_dir, 
+            os.environ['USER']
+        )
+        cmds = scp_cmd.split()
+        log.msg('Copying engine_killer: %s' % scp_cmd)
+        d = getProcessOutput(cmds[0], cmds[1:], env=os.environ)
+        return d
+    
+    def _ssh_kill(self, hostname):
+        kill_cmd = "ssh %s sh %s/%s-engine_killer.sh" % (
+            hostname,
+            self.temp_dir, 
+            os.environ['USER']
+        )
+        log.msg('Killing engine: %s' % kill_cmd)
+        kill_cmd = kill_cmd.split()
+        d = getProcessOutput(kill_cmd[0], kill_cmd[1:], env=os.environ)
+        return d
+
+    def _exec_err(self, r):
+        log.msg(r)
+
 #-----------------------------------------------------------------------------
 # Main functions for the different types of clusters
 #-----------------------------------------------------------------------------
 
 # TODO:
 # The logic in these codes should be moved into classes like LocalCluster
 # MpirunCluster, PBSCluster, etc.  This would remove alot of the duplications.
 # The main functions should then just parse the command line arguments, create
 # the appropriate class and call a 'start' method.
 
 def check_security(args, cont_args):
     if (not args.x or not args.y) and not have_crypto:
         log.err("""
 OpenSSL/pyOpenSSL is not available, so we can't run in secure mode.
 Try running ipcluster with the -xy flags:  ipcluster local -xy -n 4""")
         reactor.stop()
         return False
     if args.x:
         cont_args.append('-x')
     if args.y:
         cont_args.append('-y')
     return True
 
+
 def main_local(args):
     cont_args = []
     cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
 
     # Check security settings before proceeding
     if not check_security(args, cont_args):
         return
 
     cl = ControllerLauncher(extra_args=cont_args)
     dstart = cl.start()
     def start_engines(cont_pid):
         engine_args = []
         engine_args.append('--logfile=%s' % \
             pjoin(args.logdir,'ipengine%s-' % cont_pid))
         eset = LocalEngineSet(extra_args=engine_args)
         def shutdown(signum, frame):
             log.msg('Stopping local cluster')
             # We are still playing with the times here, but these seem
             # to be reliable in allowing everything to exit cleanly.
             eset.interrupt_then_kill(0.5)
             cl.interrupt_then_kill(0.5)
             reactor.callLater(1.0, reactor.stop)
         signal.signal(signal.SIGINT,shutdown)
         d = eset.start(args.n)
         return d
     def delay_start(cont_pid):
         # This is needed because the controller doesn't start listening
         # right when it starts and the controller needs to write
         # furl files for the engine to pick up
         reactor.callLater(1.0, start_engines, cont_pid)
     dstart.addCallback(delay_start)
     dstart.addErrback(lambda f: f.raiseException())
 
+
 def main_mpirun(args):
     cont_args = []
     cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
 
     # Check security settings before proceeding
     if not check_security(args, cont_args):
         return
 
     cl = ControllerLauncher(extra_args=cont_args)
     dstart = cl.start()
     def start_engines(cont_pid):
         raw_args = ['mpirun']
         raw_args.extend(['-n',str(args.n)])
         raw_args.append('ipengine')
         raw_args.append('-l')
         raw_args.append(pjoin(args.logdir,'ipengine%s-' % cont_pid))
         if args.mpi:
             raw_args.append('--mpi=%s' % args.mpi)
         eset = ProcessLauncher(raw_args)
         def shutdown(signum, frame):
             log.msg('Stopping local cluster')
             # We are still playing with the times here, but these seem
             # to be reliable in allowing everything to exit cleanly.
             eset.interrupt_then_kill(1.0)
             cl.interrupt_then_kill(1.0)
             reactor.callLater(2.0, reactor.stop)
         signal.signal(signal.SIGINT,shutdown)
         d = eset.start()
         return d
     def delay_start(cont_pid):
         # This is needed because the controller doesn't start listening
         # right when it starts and the controller needs to write
         # furl files for the engine to pick up
         reactor.callLater(1.0, start_engines, cont_pid)
     dstart.addCallback(delay_start)
     dstart.addErrback(lambda f: f.raiseException())
 
+
 def main_pbs(args):
     cont_args = []
     cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
 
     # Check security settings before proceeding
     if not check_security(args, cont_args):
         return
 
     cl = ControllerLauncher(extra_args=cont_args)
     dstart = cl.start()
     def start_engines(r):
         pbs_set =  PBSEngineSet(args.pbsscript)
         def shutdown(signum, frame):
             log.msg('Stopping pbs cluster')
             d = pbs_set.kill()
             d.addBoth(lambda _: cl.interrupt_then_kill(1.0))
             d.addBoth(lambda _: reactor.callLater(2.0, reactor.stop))
         signal.signal(signal.SIGINT,shutdown)
         d = pbs_set.start(args.n)
         return d
     dstart.addCallback(start_engines)
     dstart.addErrback(lambda f: f.raiseException())
 
 
+def main_ssh(args):
+    """Start a controller on localhost and engines using ssh.
+    
+    Your clusterfile should look like::
+    
+        send_furl = False # True, if you want 
+        engines = {
+            'engine_host1' : engine_count, 
+            'engine_host2' : engine_count2
+        } 
+    """
+    clusterfile = {}
+    execfile(args.clusterfile, clusterfile)
+    if not clusterfile.has_key('send_furl'):
+        clusterfile['send_furl'] = False
+        
+    cont_args = []
+    cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
+    
+    # Check security settings before proceeding
+    if not check_security(args, cont_args):
+        return
+    
+    cl = ControllerLauncher(extra_args=cont_args)
+    dstart = cl.start()
+    def start_engines(cont_pid):
+        ssh_set = SSHEngineSet(clusterfile['engines'], sshx=args.sshx)
+        def shutdown(signum, frame):
+            d = ssh_set.kill()
+            # d.addErrback(log.err)
+            cl.interrupt_then_kill(1.0)
+            reactor.callLater(2.0, reactor.stop)
+        signal.signal(signal.SIGINT,shutdown)
+        d = ssh_set.start(clusterfile['send_furl'])
+        return d
+    
+    def delay_start(cont_pid):
+        reactor.callLater(1.0, start_engines, cont_pid)
+        
+    dstart.addCallback(delay_start)
+    dstart.addErrback(lambda f: f.raiseException())
+
+
 def get_args():
     base_parser = argparse.ArgumentParser(add_help=False)
     base_parser.add_argument(
         '-x',
         action='store_true',
         dest='x',
         help='turn off client security'
     )
     base_parser.add_argument(
         '-y',
         action='store_true',
         dest='y',
         help='turn off engine security'
     )
     base_parser.add_argument(
         "--logdir", 
         type=str,
         dest="logdir",
         help="directory to put log files (default=$IPYTHONDIR/log)",
         default=pjoin(get_ipython_dir(),'log')
     )
     base_parser.add_argument(
         "-n",
         "--num", 
         type=int,
         dest="n",
         default=2,
         help="the number of engines to start"
     )
     
     parser = argparse.ArgumentParser(
         description='IPython cluster startup.  This starts a controller and\
         engines using various approaches.  THIS IS A TECHNOLOGY PREVIEW AND\
         THE API WILL CHANGE SIGNIFICANTLY BEFORE THE FINAL RELEASE.'
     )
     subparsers = parser.add_subparsers(
         help='available cluster types.  For help, do "ipcluster TYPE --help"')
     
     parser_local = subparsers.add_parser(
         'local',
         help='run a local cluster',
         parents=[base_parser]
     )
     parser_local.set_defaults(func=main_local)
     
     parser_mpirun = subparsers.add_parser(
         'mpirun',
         help='run a cluster using mpirun',
         parents=[base_parser]
     )
     parser_mpirun.add_argument(
         "--mpi",
         type=str,
         dest="mpi", # Don't put a default here to allow no MPI support
         help="how to call MPI_Init (default=mpi4py)"
     )
     parser_mpirun.set_defaults(func=main_mpirun)
     
     parser_pbs = subparsers.add_parser(
         'pbs', 
         help='run a pbs cluster',
         parents=[base_parser]
     )
     parser_pbs.add_argument(
         '--pbs-script',
         type=str, 
         dest='pbsscript',
         help='PBS script template',
         default='pbs.template'
     )
     parser_pbs.set_defaults(func=main_pbs)
+    
+    parser_ssh = subparsers.add_parser(
+        'ssh',
+        help='run a cluster using ssh, should have ssh-keys setup',
+        parents=[base_parser]
+    )
+    parser_ssh.add_argument(
+        '--clusterfile', 
+        type=str,
+        dest='clusterfile',
+        help='python file describing the cluster',
+        default='clusterfile.py',
+    )
+    parser_ssh.add_argument(
+        '--sshx', 
+        type=str,
+        dest='sshx',
+        help='sshx launcher helper'
+    )
+    parser_ssh.set_defaults(func=main_ssh)
+    
     args = parser.parse_args()
     return args
 
 def main():
     args = get_args()
     reactor.callWhenRunning(args.func, args)
     log.startLogging(sys.stdout)
     reactor.run()
 
 if __name__ == '__main__':
     main()

docs/source/changes.txt

@@ -1,393 +1,398 b''
 .. _changes:
 
 ==========
 What's new
 ==========
 
 .. contents::
 ..
     1  Release 0.9.1
     2  Release 0.9
       2.1  New features
       2.2  Bug fixes
       2.3  Backwards incompatible changes
       2.4  Changes merged in from IPython1
         2.4.1  New features
         2.4.2  Bug fixes
         2.4.3  Backwards incompatible changes
     3  Release 0.8.4
     4  Release 0.8.3
     5  Release 0.8.2
     6  Older releases
 ..
 
 Release dev
 ===========
 
 New features
 ------------
 
+* The new ipcluster now has a fully working ssh mode that should work on
+  Linux, Unix and OS X.  Thanks to Vishal Vatsa for implementing this!
+
 * The wonderful TextMate editor can now be used with %edit on OS X.  Thanks
   to Matt Foster for this patch.
 
 * Fully refactored :command:`ipcluster` command line program for starting
   IPython clusters.  This new version is a complete rewrite and 1) is fully
   cross platform (we now use Twisted's process management), 2) has much
   improved performance, 3) uses subcommands for different types of clusters, 
   4) uses argparse for parsing command line options, 5) has better support
   for starting clusters using :command:`mpirun`, 6) has experimental support
   for starting engines using PBS.  However, this new version of ipcluster
   should be considered a technology preview.  We plan on changing the API
   in significant ways before it is final.
 
 * The :mod:`argparse` module has been added to :mod:`IPython.external`.
 
 * Fully description of the security model added to the docs.
 
 * cd completer: show bookmarks if no other completions are available.
 
 * sh profile: easy way to give 'title' to prompt: assign to variable
   '_prompt_title'. It looks like this::
       
         [~]|1> _prompt_title = 'sudo!'
         sudo![~]|2>
 
 * %edit: If you do '%edit pasted_block', pasted_block
   variable gets updated with new data (so repeated 
   editing makes sense)
 
 Bug fixes
 ---------
 
+* Numerous bugs on Windows with the new ipcluster have been fixed.
+
 * The ipengine and ipcontroller scripts now handle missing furl files
   more gracefully by giving better error messages.
 
 * %rehashx: Aliases no longer contain dots. python3.0 binary
   will create alias python30. Fixes:
   #259716 "commands with dots in them don't work"
 
 * %cpaste: %cpaste -r repeats the last pasted block.
   The block is assigned to pasted_block even if code
   raises exception.
 
 Backwards incompatible changes
 ------------------------------
 
 * The controller now has a ``-r`` flag that needs to be used if you want to
   reuse existing furl files.  Otherwise they are deleted (the default).
 
 * Remove ipy_leo.py. "easy_install ipython-extension" to get it.
   (done to decouple it from ipython release cycle)
 
 
 
 Release 0.9.1
 =============
 
 This release was quickly made to restore compatibility with Python 2.4, which
 version 0.9 accidentally broke.  No new features were introduced, other than
 some additional testing support for internal use.
 
 
 Release 0.9
 ===========
 
 New features
 ------------
 
 * All furl files and security certificates are now put in a read-only
   directory named ~./ipython/security.
 
 * A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that
   determines the user's IPython directory in a robust manner.
 
 * Laurent's WX application has been given a top-level script called
   ipython-wx, and it has received numerous fixes. We expect this code to be
   architecturally better integrated with Gael's WX 'ipython widget' over the
   next few releases.
 
 * The Editor synchronization work by Vivian De Smedt has been merged in.  This
   code adds a number of new editor hooks to synchronize with editors under
   Windows.
 
 * A new, still experimental but highly functional, WX shell by Gael Varoquaux.
   This work was sponsored by Enthought, and while it's still very new, it is
   based on a more cleanly organized arhictecture of the various IPython
   components. We will continue to develop this over the next few releases as a
   model for GUI components that use IPython.
 
 * Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework),
   authored by Barry Wark.  Currently the WX and the Cocoa ones have slightly
   different internal organizations, but the whole team is working on finding
   what the right abstraction points are for a unified codebase.
 
 * As part of the frontend work, Barry Wark also implemented an experimental
   event notification system that various ipython components can use.  In the
   next release the implications and use patterns of this system regarding the
   various GUI options will be worked out.
 
 * IPython finally has a full test system, that can test docstrings with
   IPython-specific functionality.  There are still a few pieces missing for it
   to be widely accessible to all users (so they can run the test suite at any
   time and report problems), but it now works for the developers.  We are
   working hard on continuing to improve it, as this was probably IPython's
   major Achilles heel (the lack of proper test coverage made it effectively
   impossible to do large-scale refactoring).  The full test suite can now
   be run using the :command:`iptest` command line program.
 
 * The notion of a task has been completely reworked.  An `ITask` interface has
   been created.  This interface defines the methods that tasks need to
   implement.  These methods are now responsible for things like submitting
   tasks and processing results.  There are two basic task types:
   :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but
   renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on
   a function.
 
 * A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to
   standardize the idea of a `map` method.  This interface has a single `map`
   method that has the same syntax as the built-in `map`.  We have also defined
   a `mapper` factory interface that creates objects that implement
   :class:`IPython.kernel.mapper.IMapper` for different controllers.  Both the
   multiengine and task controller now have mapping capabilties.
 
 * The parallel function capabilities have been reworks.  The major changes are
   that i) there is now an `@parallel` magic that creates parallel functions,
   ii) the syntax for mulitple variable follows that of `map`, iii) both the
   multiengine and task controller now have a parallel function implementation.
 
 * All of the parallel computing capabilities from `ipython1-dev` have been
   merged into IPython proper.  This resulted in the following new subpackages:
   :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
   :mod:`IPython.tools` and :mod:`IPython.testing`.
 
 * As part of merging in the `ipython1-dev` stuff, the `setup.py` script and
   friends have been completely refactored.  Now we are checking for
   dependencies using the approach that matplotlib uses.
 
 * The documentation has been completely reorganized to accept the 
   documentation from `ipython1-dev`.
 
 * We have switched to using Foolscap for all of our network protocols in
   :mod:`IPython.kernel`.  This gives us secure connections that are both
   encrypted and authenticated.
 
 * We have a brand new `COPYING.txt` files that describes the IPython license
   and copyright. The biggest change is that we are putting "The IPython
   Development Team" as the copyright holder. We give more details about
   exactly what this means in this file. All developer should read this and use
   the new banner in all IPython source code files.
 
 * sh profile: ./foo runs foo as system command, no need to do !./foo anymore
 
 * String lists now support ``sort(field, nums = True)`` method (to easily sort
   system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``.
 
 * '%cpaste foo' now assigns the pasted block as string list, instead of string
 
 * The ipcluster script now run by default with no security.  This is done
   because the main usage of the script is for starting things on localhost.
   Eventually when ipcluster is able to start things on other hosts, we will put
   security back.
 
 * 'cd --foo' searches directory history for string foo, and jumps to that dir.
   Last part of dir name is checked first. If no matches for that are found,
   look at the whole path.
 
   
 Bug fixes
 ---------
 
 * The Windows installer has been fixed.  Now all IPython scripts have ``.bat``
   versions created.  Also, the Start Menu shortcuts have been updated.
 
 * The colors escapes in the multiengine client are now turned off on win32 as
   they don't print correctly.
 
 * The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing
   mpi_import_statement incorrectly, which was leading the engine to crash when
   mpi was enabled.
 
 * A few subpackages had missing ``__init__.py`` files.
 
 * The documentation is only created if Sphinx is found.  Previously, the
   ``setup.py`` script would fail if it was missing.
 
 * Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as
   it caused problems on certain platforms.
           
 
 Backwards incompatible changes
 ------------------------------
 
 * The ``clusterfile`` options of the :command:`ipcluster` command has been
   removed as it was not working and it will be replaced soon by something much
   more robust.
 
 * The :mod:`IPython.kernel` configuration now properly find the user's
   IPython directory.
 
 * In ipapi, the :func:`make_user_ns` function has been replaced with
   :func:`make_user_namespaces`, to support dict subclasses in namespace
   creation.
 
 * :class:`IPython.kernel.client.Task` has been renamed
   :class:`IPython.kernel.client.StringTask` to make way for new task types.
 
 * The keyword argument `style` has been renamed `dist` in `scatter`, `gather`
   and `map`.
 
 * Renamed the values that the rename `dist` keyword argument can have from
   `'basic'` to `'b'`.
 
 * IPython has a larger set of dependencies if you want all of its capabilities.
   See the `setup.py` script for details.
 
 * The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
   :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
   Instead they take the filename of a file that contains the FURL for that
   client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
   and the constructor can be left empty.
 
 * The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
   using the factory functions :func:`get_multiengine_client` and 
   :func:`get_task_client`.  These return a `Deferred` to the actual client.
 
 * The command line options to `ipcontroller` and `ipengine` have changed to
   reflect the new Foolscap network protocol and the FURL files.  Please see the
   help for these scripts for details.
 
 * The configuration files for the kernel have changed because of the Foolscap
   stuff.  If you were using custom config files before, you should delete them
   and regenerate new ones.
 
 Changes merged in from IPython1
 -------------------------------
 
 New features
 ............
 
 * Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted and
   zope.interface are now easy installable, we can declare them as dependencies
   in our setupegg.py script.
 
 * IPython is now compatible with Twisted 2.5.0 and 8.x.
 
 * Added a new example of how to use :mod:`ipython1.kernel.asynclient`.
 
 * Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
   been merged into IPython and is still in `ipython1-dev`.
   
 * The ``TaskController`` now has methods for getting the queue status.
 
 * The ``TaskResult`` objects not have information about how long the task
   took to run.
   
 * We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
   we use to carry additional info around.
   
 * New top-level module :mod:`asyncclient` that has asynchronous versions (that
   return deferreds) of the client classes.  This is designed to users who want
   to run their own Twisted reactor.
   
 * All the clients in :mod:`client` are now based on Twisted.  This is done by 
   running the Twisted reactor in a separate thread and using the
   :func:`blockingCallFromThread` function that is in recent versions of Twisted.
 
 * Functions can now be pushed/pulled to/from engines using
   :meth:`MultiEngineClient.push_function` and
   :meth:`MultiEngineClient.pull_function`.
 
 * Gather/scatter are now implemented in the client to reduce the work load
   of the controller and improve performance.
 
 * Complete rewrite of the IPython docuementation.  All of the documentation
   from the IPython website has been moved into docs/source as restructured
   text documents.  PDF and HTML documentation are being generated using 
   Sphinx.
 
 * New developer oriented documentation: development guidelines and roadmap. 
 
 * Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt``
   file that is organized by release and is meant to provide something more
   relevant for users.
 
 Bug fixes
 .........
 
 * Created a proper ``MANIFEST.in`` file to create source distributions.
 
 * Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
   actions were being collected with a :class:`DeferredList` with 
   ``fireononeerrback=1``.  This meant that methods were returning 
   before all engines had given their results.  This was causing extremely odd 
   bugs in certain cases. To fix this problem, we have 1) set 
   ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
   before returning and 2) introduced a :exc:`CompositeError` exception 
   that wraps all of the engine exceptions.  This is a huge change as it means 
   that users will have to catch :exc:`CompositeError` rather than the actual
   exception.
 
 Backwards incompatible changes
 ..............................
 
 * All names have been renamed to conform to the lowercase_with_underscore
   convention.  This will require users to change references to all names like
   ``queueStatus`` to ``queue_status``.
 
 * Previously, methods like :meth:`MultiEngineClient.push` and
   :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was
   becoming a problem as we weren't able to introduce new keyword arguments into
   the API.  Now these methods simple take a dict or sequence.  This has also
   allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and
   :meth:`pullAll`.  These things are now handled with the ``targets`` keyword
   argument that defaults to ``'all'``.
 
 * The :attr:`MultiEngineClient.magicTargets` has been renamed to
   :attr:`MultiEngineClient.targets`. 
 
 * All methods in the MultiEngine interface now accept the optional keyword
   argument ``block``.
 
 * Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
   :class:`TaskController` to :class:`TaskClient`.
 
 * Renamed the top-level module from :mod:`api` to :mod:`client`.
 
 * Most methods in the multiengine interface now raise a :exc:`CompositeError`
   exception that wraps the user's exceptions, rather than just raising the raw
   user's exception.
 
 * Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
   and ``pull``.
 
   
 Release 0.8.4
 =============
 
 This was a quick release to fix an unfortunate bug that slipped into the 0.8.3
 release.  The ``--twisted`` option was disabled, as it turned out to be broken
 across several platforms.
 
 
 Release 0.8.3
 =============
   
 * pydb is now disabled by default (due to %run -d problems). You can enable
   it by passing -pydb command line argument to IPython. Note that setting
   it in config file won't work.
 
   
 Release 0.8.2
 =============
 
 * %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
   and jumps to /foo. The current behaviour is closer to the documented 
   behaviour, and should not trip anyone.
 
   
 Older releases
 ==============
 
 Changes in earlier releases of IPython are described in the older file
 ``ChangeLog``.  Please refer to this document for details.
 

docs/source/parallel/parallel_process.txt

@@ -1,251 +1,324 b''
 .. _parallel_process:
 
 ===========================================
 Starting the IPython controller and engines
 ===========================================
 
 To use IPython for parallel computing, you need to start one instance of
 the controller and one or more instances of the engine. The controller
 and each engine can run on different machines or on the same machine.
 Because of this, there are many different possibilities.
 
 Broadly speaking, there are two ways of going about starting a controller and engines:
 
 * In an automated manner using the :command:`ipcluster` command.
 * In a more manual way using the :command:`ipcontroller` and 
   :command:`ipengine` commands.
 
 This document describes both of these methods.  We recommend that new users start with the :command:`ipcluster` command as it simplifies many common usage cases.
 
 General considerations
 ======================
 
 Before delving into the details about how you can start a controller and engines using the various methods, we outline some of the general issues that come up when starting the controller and engines.  These things come up no matter which method you use to start your IPython cluster.
 
 Let's say that you want to start the controller on ``host0`` and engines on hosts ``host1``-``hostn``.  The following steps are then required:
 
 1. Start the controller on ``host0`` by running :command:`ipcontroller` on
    ``host0``.
 2. Move the FURL file (:file:`ipcontroller-engine.furl`) created by the 
    controller from ``host0`` to hosts ``host1``-``hostn``.
 3. Start the engines on hosts ``host1``-``hostn`` by running 
    :command:`ipengine`.  This command has to be told where the FURL file 
    (:file:`ipcontroller-engine.furl`) is located.
 
 At this point, the controller and engines will be connected. By default, the
 FURL files created by the controller are put into the
 :file:`~/.ipython/security` directory. If the engines share a filesystem with
 the controller, step 2 can be skipped as the engines will automatically look
 at that location.
 
 The final step required required to actually use the running controller from a
 client is to move the FURL files :file:`ipcontroller-mec.furl` and
 :file:`ipcontroller-tc.furl` from ``host0`` to the host where the clients will
 be run.  If these file are put into the :file:`~/.ipython/security` directory of the client's host, they will be found automatically.  Otherwise, the full path to them has to be passed to the client's constructor.
 
 Using :command:`ipcluster`
 ==========================
 
 The :command:`ipcluster` command provides a simple way of starting a controller and engines in the following situations:
 
 1. When the controller and engines are all run on localhost. This is useful
    for testing or running on a multicore computer.
 2. When engines are started using the :command:`mpirun` command that comes 
    with most MPI [MPI]_ implementations
 3. When engines are started using the PBS [PBS]_ batch system.
+4. When the controller is started on localhost and the engines are started on 
+   remote nodes using :command:`ssh`.
 
 .. note::
 
     It is also possible for advanced users to add support to
     :command:`ipcluster` for starting controllers and engines using other
     methods (like Sun's Grid Engine for example).
 
 .. note::
 
     Currently :command:`ipcluster` requires that the
     :file:`~/.ipython/security` directory live on a shared filesystem that is
     seen by both the controller and engines. If you don't have a shared file
     system you will need to use :command:`ipcontroller` and
-    :command:`ipengine` directly.
+    :command:`ipengine` directly.  This constraint can be relaxed if you are 
+    using the :command:`ssh` method to start the cluster.
 
 Underneath the hood, :command:`ipcluster` just uses :command:`ipcontroller`
 and :command:`ipengine` to perform the steps described above.
 
 Using :command:`ipcluster` in local mode
 ----------------------------------------
 
 To start one controller and 4 engines on localhost, just do::
 
     $ ipcluster local -n 4
 
 To see other command line options for the local mode, do::
 
     $ ipcluster local -h
 
 Using :command:`ipcluster` in mpirun mode
 -----------------------------------------
 
 The mpirun mode is useful if you:
 
 1. Have MPI installed.
 2. Your systems are configured to use the :command:`mpirun` command to start 
    processes.
 
 If these are satisfied, you can start an IPython cluster using::
 
     $ ipcluster mpirun -n 4
 
 This does the following:
 
 1. Starts the IPython controller on current host.
 2. Uses :command:`mpirun` to start 4 engines.
 
 On newer MPI implementations (such as OpenMPI), this will work even if you don't make any calls to MPI or call :func:`MPI_Init`.  However, older MPI implementations actually require each process to call :func:`MPI_Init` upon starting.  The easiest way of having this done is to install the mpi4py [mpi4py]_ package and then call ipcluster with the ``--mpi`` option::
 
     $ ipcluster mpirun -n 4 --mpi=mpi4py
 
 Unfortunately, even this won't work for some MPI implementations.  If you are having problems with this, you will likely have to use a custom Python executable that itself calls :func:`MPI_Init` at the appropriate time.  Fortunately, mpi4py comes with such a custom Python executable that is easy to install and use.  However, this custom Python executable approach will not work with :command:`ipcluster` currently.
 
 Additional command line options for this mode can be found by doing::
 
     $ ipcluster mpirun -h
 
 More details on using MPI with IPython can be found :ref:`here <parallelmpi>`.
 
 
 Using :command:`ipcluster` in PBS mode
 --------------------------------------
 
 The PBS mode uses the Portable Batch System [PBS]_ to start the engines.  To use this mode, you first need to create a PBS script template that will be used to start the engines.  Here is a sample PBS script template:
 
 .. sourcecode:: bash
 
     #PBS -N ipython
     #PBS -j oe
     #PBS -l walltime=00:10:00
     #PBS -l nodes=${n/4}:ppn=4
     #PBS -q parallel
 
     cd $$PBS_O_WORKDIR
     export PATH=$$HOME/usr/local/bin
     export PYTHONPATH=$$HOME/usr/local/lib/python2.4/site-packages
     /usr/local/bin/mpiexec -n ${n} ipengine --logfile=$$PBS_O_WORKDIR/ipengine
 
 There are a few important points about this template:
 
 1. This template will be rendered at runtime using IPython's :mod:`Itpl` 
    template engine.
 
 2. Instead of putting in the actual number of engines, use the notation
    ``${n}`` to indicate the number of engines to be started. You can also uses
    expressions like ``${n/4}`` in the template to indicate the number of 
    nodes.
 
 3. Because ``$`` is a special character used by the template engine, you must  
    escape any ``$`` by using ``$$``.  This is important when referring to 
    environment variables in the template.
 
 4. Any options to :command:`ipengine` should be given in the batch script 
    template.
 
 5. Depending on the configuration of you system, you may have to set 
    environment variables in the script template.
 
 Once you have created such a script, save it with a name like :file:`pbs.template`.  Now you are ready to start your job::
 
     $ ipcluster pbs -n 128 --pbs-script=pbs.template
 
 Additional command line options for this mode can be found by doing::
 
     $ ipcluster pbs -h
 
+Using :command:`ipcluster` in SSH mode
+--------------------------------------
+
+The SSH mode uses :command:`ssh` to execute :command:`ipengine` on remote
+nodes and the :command:`ipcontroller` on localhost.
+
+When using using this mode it highly recommended that you have set up SSH keys and are using ssh-agent [SSH]_ for password-less logins.
+
+To use this mode you need a python file describing the cluster, here is an example of such a "clusterfile":
+
+.. sourcecode:: python
+    
+    send_furl = True
+    engines = { 'host1.example.com' : 2,
+                'host2.example.com' : 5,
+                'host3.example.com' : 1,
+                'host4.example.com' : 8 }
+
+Since this is a regular python file usual python syntax applies. Things to note:
+
+* The `engines` dict, where the keys is the host we want to run engines on and
+  the value is the number of engines to run on that host.
+* send_furl can either be `True` or `False`, if `True` it will copy over the
+  furl needed for :command:`ipengine` to each host.
+
+The ``--clusterfile`` command line option lets you specify the file to use for
+the cluster definition. Once you have your cluster file and you can
+:command:`ssh` into the remote hosts with out an password you are ready to
+start your cluster like so:
+
+.. sourcecode:: bash 
+
+   $ ipcluster ssh --clusterfile /path/to/my/clusterfile.py
+
+
+Two helper shell scripts are used to start and stop :command:`ipengine` on remote hosts:
+
+* sshx.sh 
+* engine_killer.sh
+
+Defaults for both of these are contained in the source code for :command:`ipcluster`. The default scripts are written to a local file in a tmep directory and then copied to a temp directory on the remote host and executed from there.  On most Unix, Linux and OS X systems this is /tmp.
+
+The default sshx.sh is the following:
+
+.. sourcecode:: bash
+
+   #!/bin/sh
+   "$@" &> /dev/null &
+   echo $!
+
+If you want to use a custom sshx.sh script you need to use the ``--sshx``
+option and specify the file to use. Using a custom sshx.sh file could be
+helpful when you need to setup the environment on the remote host before
+executing :command:`ipengine`.
+
+For a detailed options list:
+
+.. sourcecode:: bash
+
+   $ ipcluster ssh -h
+
+Current limitations of the SSH mode of :command:`ipcluster` are:
+
+* Untested on Windows. Would require a working :command:`ssh` on Windows.
+  Also, we are using shell scripts to setup and execute commands on remote
+  hosts.
+* :command:`ipcontroller` is started on localhost, with no option to start it
+  on a remote node.
+
 Using the :command:`ipcontroller` and :command:`ipengine` commands
 ==================================================================
 
 It is also possible to use the :command:`ipcontroller` and :command:`ipengine` commands to start your controller and engines.  This approach gives you full control over all aspects of the startup process.
 
 Starting the controller and engine on your local machine
 --------------------------------------------------------
 
 To use :command:`ipcontroller` and :command:`ipengine` to start things on your
 local machine, do the following.
 
 First start the controller::
 
 	$ ipcontroller
 	
 Next, start however many instances of the engine you want using (repeatedly) the command::
 
 	$ ipengine
 
 The engines should start and automatically connect to the controller using the FURL files in :file:`~./ipython/security`. You are now ready to use the controller and engines from IPython.
 
 .. warning:: 
 	
 	The order of the above operations is very important.  You *must*
  	start the controller before the engines, since the engines connect 
 	to the controller as they get started.
 
 .. note::
 
     On some platforms (OS X), to put the controller and engine into the
     background you may need to give these commands in the form ``(ipcontroller
     &)`` and ``(ipengine &)`` (with the parentheses) for them to work
     properly.
 
 Starting the controller and engines on different hosts
 ------------------------------------------------------
 
 When the controller and engines are running on different hosts, things are
 slightly more complicated, but the underlying ideas are the same:
 
 1. Start the controller on a host using :command:`ipcontroller`.
 2. Copy :file:`ipcontroller-engine.furl` from :file:`~./ipython/security` on the controller's host to the host where the engines will run.
 3. Use :command:`ipengine` on the engine's hosts to start the engines.
 
 The only thing you have to be careful of is to tell :command:`ipengine` where the :file:`ipcontroller-engine.furl` file is located.  There are two ways you can do this:
 
 * Put :file:`ipcontroller-engine.furl` in the :file:`~./ipython/security`
   directory on the engine's host, where it will be found automatically.
 * Call :command:`ipengine` with the ``--furl-file=full_path_to_the_file``
   flag.
 
 The ``--furl-file`` flag works like this::
 
     $ ipengine --furl-file=/path/to/my/ipcontroller-engine.furl
 
 .. note::
     
     If the controller's and engine's hosts all have a shared file system  
     (:file:`~./ipython/security` is the same on all of them), then things
     will just work!
 
 Make FURL files persistent
 ---------------------------
 
 At fist glance it may seem that that managing the FURL files is a bit annoying.  Going back to the house and key analogy, copying the FURL around each time you start the controller is like having to make a new key every time you want to unlock the door and enter your house.  As with your house, you want to be able to create the key (or FURL file) once, and then simply use it at any point in the future.
 
 This is possible.  The only thing you have to do is decide what ports the controller will listen on for the engines and clients.  This is done as follows::
 
     $ ipcontroller -r --client-port=10101 --engine-port=10102
 
 Then, just copy the furl files over the first time and you are set.  You can start and stop the controller and engines any many times as you want in the future, just make sure to tell the controller to use the *same* ports.
 
 .. note::
 
     You may ask the question: what ports does the controller listen on if you
     don't tell is to use specific ones? The default is to use high random port
     numbers. We do this for two reasons: i) to increase security through
     obscurity and ii) to multiple controllers on a given host to start and
     automatically use different ports.
 
 Log files
 ---------
 
 All of the components of IPython have log files associated with them.
 These log files can be extremely useful in debugging problems with
 IPython and can be found in the directory :file:`~/.ipython/log`.  Sending
 the log files to us will often help us to debug any problems.
 
 
 .. [PBS] Portable Batch System.  http://www.openpbs.org/
+.. [SSH] SSH-Agent http://en.wikipedia.org/wiki/Ssh-agent