API update involving map and load-balancing

IPython/utils/newserialized.py

@@ -1,165 +1,165 b''
 # encoding: utf-8
 # -*- test-case-name: IPython.kernel.test.test_newserialized -*-
 
 """Refactored serialization classes and interfaces."""
 
 __docformat__ = "restructuredtext en"
 
 # Tell nose to skip this module
 __test__ = {}
 
 #-------------------------------------------------------------------------------
 #  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
 
 try:
     import numpy
 except ImportError:
     pass
 
 class SerializationError(Exception):
     pass
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class ISerialized:
     
     def getData():
         """"""
 
     def getDataSize(units=10.0**6):
         """"""
 
     def getTypeDescriptor():
         """"""
 
     def getMetadata():
         """"""
         
         
 class IUnSerialized:
     
     def getObject():
         """"""
         
 class Serialized(object):
     
     # implements(ISerialized)
     
     def __init__(self, data, typeDescriptor, metadata={}):
         self.data = data
         self.typeDescriptor = typeDescriptor
         self.metadata = metadata
         
     def getData(self):
         return self.data
         
     def getDataSize(self, units=10.0**6):
         return len(self.data)/units
         
     def getTypeDescriptor(self):
         return self.typeDescriptor
         
     def getMetadata(self):
         return self.metadata
 
         
 class UnSerialized(object):
     
     # implements(IUnSerialized)
         
     def __init__(self, obj):
         self.obj = obj
         
     def getObject(self):
         return self.obj
 
         
 class SerializeIt(object):
     
     # implements(ISerialized)
     
     def __init__(self, unSerialized):
         self.data = None
         self.obj = unSerialized.getObject()
         if globals().has_key('numpy') and isinstance(self.obj, numpy.ndarray):
                 if len(self.obj) == 0:         # length 0 arrays can't be reconstructed
                     raise SerializationError("You cannot send a length 0 array")
                 self.obj = numpy.ascontiguousarray(self.obj, dtype=None)
                 self.typeDescriptor = 'ndarray'
                 self.metadata = {'shape':self.obj.shape,
                                  'dtype':self.obj.dtype.str}
         elif isinstance(self.obj, str):
             self.typeDescriptor = 'bytes'
             self.metadata = {}
         elif isinstance(self.obj, buffer):
             self.typeDescriptor = 'buffer'
             self.metadata = {}
         else:
             self.typeDescriptor = 'pickle'
             self.metadata = {}
         self._generateData()            
     
     def _generateData(self):
         if self.typeDescriptor == 'ndarray':
             self.data = numpy.getbuffer(self.obj)
         elif self.typeDescriptor in ('bytes', 'buffer'):
             self.data = self.obj
         elif self.typeDescriptor == 'pickle':
             self.data = pickle.dumps(self.obj, -1)
         else:
             raise SerializationError("Really wierd serialization error.")
         del self.obj
         
     def getData(self):
         return self.data
         
     def getDataSize(self, units=10.0**6):
         return 1.0*len(self.data)/units
         
     def getTypeDescriptor(self):
         return self.typeDescriptor
         
     def getMetadata(self):
         return self.metadata
 
 
 class UnSerializeIt(UnSerialized):
     
     # implements(IUnSerialized)
     
     def __init__(self, serialized):
         self.serialized = serialized
         
     def getObject(self):
         typeDescriptor = self.serialized.getTypeDescriptor()
         if globals().has_key('numpy') and typeDescriptor == 'ndarray':
                 result = numpy.frombuffer(self.serialized.getData(), dtype = self.serialized.metadata['dtype'])
                 result.shape = self.serialized.metadata['shape']
-                # This is a hack to make the array writable.  We are working with
+                # numpy arrays with frombuffer are read-only.  We are working with
                 # the numpy folks to address this issue.
-                result = result.copy()
+                # result = result.copy()
         elif typeDescriptor == 'pickle':
             result = pickle.loads(self.serialized.getData())
         elif typeDescriptor in ('bytes', 'buffer'):
             result = self.serialized.getData()
         else:
             raise SerializationError("Really wierd serialization error.")
         return result
 
 def serialize(obj):
     return SerializeIt(UnSerialized(obj))
     
 def unserialize(serialized):
     return UnSerializeIt(serialized).getObject()

IPython/zmq/parallel/client.py

@@ -1,1472 +1,1328 b''
 """A semi-synchronous Client for the ZMQ controller"""
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  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 json
 import time
 import warnings
 from datetime import datetime
 from getpass import getpass
 from pprint import pprint
 
 pjoin = os.path.join
 
 import zmq
-from zmq.eventloop import ioloop, zmqstream
+# from zmq.eventloop import ioloop, zmqstream
 
 from IPython.utils.path import get_ipython_dir
 from IPython.external.decorator import decorator
 from IPython.external.ssh import tunnel
 
 import error
 import map as Map
 import streamsession as ss
 from asyncresult import AsyncResult, AsyncMapResult
 from clusterdir import ClusterDir, ClusterDirError
 from dependency import Dependency, depend, require, dependent
 from remotefunction import remote,parallel,ParallelFunction,RemoteFunction
 from util import ReverseDict, disambiguate_url, validate_url
 from view import DirectView, LoadBalancedView
 
 #--------------------------------------------------------------------------
 # helpers for implementing old MEC API via client.apply
 #--------------------------------------------------------------------------
 
 def _push(ns):
     """helper method for implementing `client.push` via `client.apply`"""
     globals().update(ns)
 
 def _pull(keys):
     """helper method for implementing `client.pull` via `client.apply`"""
     g = globals()
     if isinstance(keys, (list,tuple, set)):
         for key in keys:
             if not g.has_key(key):
                 raise NameError("name '%s' is not defined"%key)
         return map(g.get, keys)
     else:
         if not g.has_key(keys):
             raise NameError("name '%s' is not defined"%keys)
         return g.get(keys)
 
 def _clear():
     """helper method for implementing `client.clear` via `client.apply`"""
     globals().clear()
 
 def _execute(code):
     """helper method for implementing `client.execute` via `client.apply`"""
     exec code in globals()
     
 
 #--------------------------------------------------------------------------
 # Decorators for Client methods
 #--------------------------------------------------------------------------
 
 @decorator
 def spinfirst(f, self, *args, **kwargs):
     """Call spin() to sync state prior to calling the method."""
     self.spin()
     return f(self, *args, **kwargs)
 
 @decorator
 def defaultblock(f, self, *args, **kwargs):
     """Default to self.block; preserve self.block."""
     block = kwargs.get('block',None)
     block = self.block if block is None else block
     saveblock = self.block
     self.block = block
     try:
         ret = f(self, *args, **kwargs)
     finally:
         self.block = saveblock
     return ret
 
 
 #--------------------------------------------------------------------------
 # Classes
 #--------------------------------------------------------------------------
 
 class Metadata(dict):
     """Subclass of dict for initializing metadata values.
     
     Attribute access works on keys.
     
     These objects have a strict set of keys - errors will raise if you try
     to add new keys.
     """
     def __init__(self, *args, **kwargs):
         dict.__init__(self)
         md = {'msg_id' : None,
               'submitted' : None,
               'started' : None,
               'completed' : None,
               'received' : None,
               'engine_uuid' : None,
               'engine_id' : None,
               'follow' : None,
               'after' : None,
               'status' : None,
 
               'pyin' : None,
               'pyout' : None,
               'pyerr' : None,
               'stdout' : '',
               'stderr' : '',
             }
         self.update(md)
         self.update(dict(*args, **kwargs))
     
     def __getattr__(self, key):
         """getattr aliased to getitem"""
         if key in self.iterkeys():
             return self[key]
         else:
             raise AttributeError(key)
 
     def __setattr__(self, key, value):
         """setattr aliased to setitem, with strict"""
         if key in self.iterkeys():
             self[key] = value
         else:
             raise AttributeError(key)
     
     def __setitem__(self, key, value):
         """strict static key enforcement"""
         if key in self.iterkeys():
             dict.__setitem__(self, key, value)
         else:
             raise KeyError(key)
         
 
 class Client(object):
     """A semi-synchronous client to the IPython ZMQ controller
     
     Parameters
     ----------
     
     url_or_file : bytes; zmq url or path to ipcontroller-client.json
         Connection information for the Hub's registration.  If a json connector
         file is given, then likely no further configuration is necessary.
         [Default: use profile]
     profile : bytes
         The name of the Cluster profile to be used to find connector information.
         [Default: 'default']
     context : zmq.Context
         Pass an existing zmq.Context instance, otherwise the client will create its own.
     username : bytes
         set username to be passed to the Session object
     debug : bool
         flag for lots of message printing for debug purposes
  
     #-------------- ssh related args ----------------
     # These are args for configuring the ssh tunnel to be used
     # credentials are used to forward connections over ssh to the Controller
     # Note that the ip given in `addr` needs to be relative to sshserver
     # The most basic case is to leave addr as pointing to localhost (127.0.0.1),
     # and set sshserver as the same machine the Controller is on. However, 
     # the only requirement is that sshserver is able to see the Controller
     # (i.e. is within the same trusted network).
     
     sshserver : str
         A string of the form passed to ssh, i.e. 'server.tld' or '[e-mail]:port'
         If keyfile or password is specified, and this is not, it will default to
         the ip given in addr.
     sshkey : str; path to public ssh key file
         This specifies a key to be used in ssh login, default None.
         Regular default ssh keys will be used without specifying this argument.
     password : str 
         Your ssh password to sshserver. Note that if this is left None,
         you will be prompted for it if passwordless key based login is unavailable.
     paramiko : bool
         flag for whether to use paramiko instead of shell ssh for tunneling.
         [default: True on win32, False else]
     
     #------- exec authentication args -------
     # If even localhost is untrusted, you can have some protection against
     # unauthorized execution by using a key.  Messages are still sent
     # as cleartext, so if someone can snoop your loopback traffic this will
     # not help against malicious attacks.
     
     exec_key : str
         an authentication key or file containing a key
         default: None
     
     
     Attributes
     ----------
+    
     ids : set of int engine IDs
         requesting the ids attribute always synchronizes
         the registration state. To request ids without synchronization,
         use semi-private _ids attributes.
     
     history : list of msg_ids
         a list of msg_ids, keeping track of all the execution
         messages you have submitted in order.
     
     outstanding : set of msg_ids
         a set of msg_ids that have been submitted, but whose
         results have not yet been received.
     
     results : dict
         a dict of all our results, keyed by msg_id
     
     block : bool
         determines default behavior when block not specified
         in execution methods
     
     Methods
     -------
-    spin : flushes incoming results and registration state changes
-            control methods spin, and requesting `ids` also ensures up to date
-            
-    barrier : wait on one or more msg_ids
     
-    execution methods: apply/apply_bound/apply_to/apply_bound
+    spin
+        flushes incoming results and registration state changes
+        control methods spin, and requesting `ids` also ensures up to date
+    
+    barrier
+        wait on one or more msg_ids
+    
+    execution methods
+        apply
         legacy: execute, run
     
-    query methods: queue_status, get_result, purge
+    query methods
+        queue_status, get_result, purge
     
-    control methods: abort, kill
+    control methods
+        abort, shutdown
     
     """
     
     
     _connected=False
     _ssh=False
     _engines=None
     _registration_socket=None
     _query_socket=None
     _control_socket=None
     _iopub_socket=None
     _notification_socket=None
     _mux_socket=None
     _task_socket=None
     _task_scheme=None
     block = False
     outstanding=None
     results = None
     history = None
     debug = False
     targets = None
     
     def __init__(self, url_or_file=None, profile='default', cluster_dir=None, ipython_dir=None,
             context=None, username=None, debug=False, exec_key=None,
             sshserver=None, sshkey=None, password=None, paramiko=None,
             ):
         if context is None:
             context = zmq.Context()
         self.context = context
-        self.targets = 'all'
         
         self._setup_cluster_dir(profile, cluster_dir, ipython_dir)
         if self._cd is not None:
             if url_or_file is None:
                 url_or_file = pjoin(self._cd.security_dir, 'ipcontroller-client.json')
         assert url_or_file is not None, "I can't find enough information to connect to a controller!"\
             " Please specify at least one of url_or_file or profile."
         
         try:
             validate_url(url_or_file)
         except AssertionError:
             if not os.path.exists(url_or_file):
                 if self._cd:
                     url_or_file = os.path.join(self._cd.security_dir, url_or_file)
                 assert os.path.exists(url_or_file), "Not a valid connection file or url: %r"%url_or_file
             with open(url_or_file) as f:
                 cfg = json.loads(f.read())
         else:
             cfg = {'url':url_or_file}
         
         # sync defaults from args, json:
         if sshserver:
             cfg['ssh'] = sshserver
         if exec_key:
             cfg['exec_key'] = exec_key
         exec_key = cfg['exec_key']
         sshserver=cfg['ssh']
         url = cfg['url']
         location = cfg.setdefault('location', None)
         cfg['url'] = disambiguate_url(cfg['url'], location)
         url = cfg['url']
         
         self._config = cfg
         
         self._ssh = bool(sshserver or sshkey or password)
         if self._ssh and sshserver is None:
             # default to ssh via localhost
             sshserver = url.split('://')[1].split(':')[0]
         if self._ssh and password is None:
             if tunnel.try_passwordless_ssh(sshserver, sshkey, paramiko):
                 password=False
             else:
                 password = getpass("SSH Password for %s: "%sshserver)
         ssh_kwargs = dict(keyfile=sshkey, password=password, paramiko=paramiko)
         if exec_key is not None and os.path.isfile(exec_key):
             arg = 'keyfile'
         else:
             arg = 'key'
         key_arg = {arg:exec_key}
         if username is None:
             self.session = ss.StreamSession(**key_arg)
         else:
             self.session = ss.StreamSession(username, **key_arg)
         self._registration_socket = self.context.socket(zmq.XREQ)
         self._registration_socket.setsockopt(zmq.IDENTITY, self.session.session)
         if self._ssh:
             tunnel.tunnel_connection(self._registration_socket, url, sshserver, **ssh_kwargs)
         else:
             self._registration_socket.connect(url)
         self._engines = ReverseDict()
         self._ids = []
         self.outstanding=set()
         self.results = {}
         self.metadata = {}
         self.history = []
         self.debug = debug
         self.session.debug = debug
         
         self._notification_handlers = {'registration_notification' : self._register_engine,
                                     'unregistration_notification' : self._unregister_engine,
                                     }
         self._queue_handlers = {'execute_reply' : self._handle_execute_reply,
                                 'apply_reply' : self._handle_apply_reply}
         self._connect(sshserver, ssh_kwargs)
         
     
     def _setup_cluster_dir(self, profile, cluster_dir, ipython_dir):
         if ipython_dir is None:
             ipython_dir = get_ipython_dir()
         if cluster_dir is not None:
             try:
                 self._cd = ClusterDir.find_cluster_dir(cluster_dir)
             except ClusterDirError:
                 pass
         elif profile is not None:
             try:
                 self._cd = ClusterDir.find_cluster_dir_by_profile(
                     ipython_dir, profile)
             except ClusterDirError:
                 pass
         else:
             self._cd = None
     
     @property
     def ids(self):
         """Always up-to-date ids property."""
         self._flush_notifications()
         return self._ids
     
     def _update_engines(self, engines):
         """Update our engines dict and _ids from a dict of the form: {id:uuid}."""
         for k,v in engines.iteritems():
             eid = int(k)
             self._engines[eid] = bytes(v) # force not unicode
             self._ids.append(eid)
         self._ids = sorted(self._ids)
         if sorted(self._engines.keys()) != range(len(self._engines)) and \
                         self._task_scheme == 'pure' and self._task_socket:
             self._stop_scheduling_tasks()
     
     def _stop_scheduling_tasks(self):
         """Stop scheduling tasks because an engine has been unregistered
         from a pure ZMQ scheduler.
         """
         
         self._task_socket.close()
         self._task_socket = None
         msg = "An engine has been unregistered, and we are using pure " +\
               "ZMQ task scheduling.  Task farming will be disabled."
         if self.outstanding:
             msg += " If you were running tasks when this happened, " +\
                    "some `outstanding` msg_ids may never resolve."
         warnings.warn(msg, RuntimeWarning)
     
     def _build_targets(self, targets):
         """Turn valid target IDs or 'all' into two lists:
         (int_ids, uuids).
         """
         if targets is None:
             targets = self._ids
         elif isinstance(targets, str):
             if targets.lower() == 'all':
                 targets = self._ids
             else:
                 raise TypeError("%r not valid str target, must be 'all'"%(targets))
         elif isinstance(targets, int):
             targets = [targets]
         return [self._engines[t] for t in targets], list(targets)
     
     def _connect(self, sshserver, ssh_kwargs):
         """setup all our socket connections to the controller. This is called from
         __init__."""
         
         # Maybe allow reconnecting?
         if self._connected:
             return
         self._connected=True
 
         def connect_socket(s, url):
             url = disambiguate_url(url, self._config['location'])
             if self._ssh:
                 return tunnel.tunnel_connection(s, url, sshserver, **ssh_kwargs)
             else:
                 return s.connect(url)
             
         self.session.send(self._registration_socket, 'connection_request')
         idents,msg = self.session.recv(self._registration_socket,mode=0)
         if self.debug:
             pprint(msg)
         msg = ss.Message(msg)
         content = msg.content
         self._config['registration'] = dict(content)
         if content.status == 'ok':
             if content.mux:
                 self._mux_socket = self.context.socket(zmq.PAIR)
                 self._mux_socket.setsockopt(zmq.IDENTITY, self.session.session)
                 connect_socket(self._mux_socket, content.mux)
             if content.task:
                 self._task_scheme, task_addr = content.task
                 self._task_socket = self.context.socket(zmq.PAIR)
                 self._task_socket.setsockopt(zmq.IDENTITY, self.session.session)
                 connect_socket(self._task_socket, task_addr)
             if content.notification:
                 self._notification_socket = self.context.socket(zmq.SUB)
                 connect_socket(self._notification_socket, content.notification)
                 self._notification_socket.setsockopt(zmq.SUBSCRIBE, "")
             if content.query:
                 self._query_socket = self.context.socket(zmq.PAIR)
                 self._query_socket.setsockopt(zmq.IDENTITY, self.session.session)
                 connect_socket(self._query_socket, content.query)
             if content.control:
                 self._control_socket = self.context.socket(zmq.PAIR)
                 self._control_socket.setsockopt(zmq.IDENTITY, self.session.session)
                 connect_socket(self._control_socket, content.control)
             if content.iopub:
                 self._iopub_socket = self.context.socket(zmq.SUB)
                 self._iopub_socket.setsockopt(zmq.SUBSCRIBE, '')
                 self._iopub_socket.setsockopt(zmq.IDENTITY, self.session.session)
                 connect_socket(self._iopub_socket, content.iopub)
             self._update_engines(dict(content.engines))
                 
         else:
             self._connected = False
             raise Exception("Failed to connect!")
     
     #--------------------------------------------------------------------------
     # handlers and callbacks for incoming messages
     #--------------------------------------------------------------------------
     
     def _register_engine(self, msg):
         """Register a new engine, and update our connection info."""
         content = msg['content']
         eid = content['id']
         d = {eid : content['queue']}
         self._update_engines(d)
 
     def _unregister_engine(self, msg):
         """Unregister an engine that has died."""
         content = msg['content']
         eid = int(content['id'])
         if eid in self._ids:
             self._ids.remove(eid)
             self._engines.pop(eid)
         if self._task_socket and self._task_scheme == 'pure':
             self._stop_scheduling_tasks()
     
     def _extract_metadata(self, header, parent, content):
         md = {'msg_id' : parent['msg_id'],
               'received' : datetime.now(),
               'engine_uuid' : header.get('engine', None),
               'follow' : parent.get('follow', []),
               'after' : parent.get('after', []),
               'status' : content['status'],
             }
         
         if md['engine_uuid'] is not None:
             md['engine_id'] = self._engines.get(md['engine_uuid'], None)
         
         if 'date' in parent:
             md['submitted'] = datetime.strptime(parent['date'], ss.ISO8601)
         if 'started' in header:
             md['started'] = datetime.strptime(header['started'], ss.ISO8601)
         if 'date' in header:
             md['completed'] = datetime.strptime(header['date'], ss.ISO8601)
         return md
     
     def _handle_execute_reply(self, msg):
         """Save the reply to an execute_request into our results.
         
         execute messages are never actually used. apply is used instead.
         """
         
         parent = msg['parent_header']
         msg_id = parent['msg_id']
         if msg_id not in self.outstanding:
             if msg_id in self.history:
                 print ("got stale result: %s"%msg_id)
             else:
                 print ("got unknown result: %s"%msg_id)
         else:
             self.outstanding.remove(msg_id)
         self.results[msg_id] = ss.unwrap_exception(msg['content'])
     
     def _handle_apply_reply(self, msg):
         """Save the reply to an apply_request into our results."""
         parent = msg['parent_header']
         msg_id = parent['msg_id']
         if msg_id not in self.outstanding:
             if msg_id in self.history:
                 print ("got stale result: %s"%msg_id)
                 print self.results[msg_id]
                 print msg
             else:
                 print ("got unknown result: %s"%msg_id)
         else:
             self.outstanding.remove(msg_id)
         content = msg['content']
         header = msg['header']
         
         # construct metadata:
         md = self.metadata.setdefault(msg_id, Metadata())
         md.update(self._extract_metadata(header, parent, content))
         self.metadata[msg_id] = md
         
         # construct result:
         if content['status'] == 'ok':
             self.results[msg_id] = ss.unserialize_object(msg['buffers'])[0]
         elif content['status'] == 'aborted':
             self.results[msg_id] = error.AbortedTask(msg_id)
         elif content['status'] == 'resubmitted':
             # TODO: handle resubmission
             pass
         else:
             e = ss.unwrap_exception(content)
             if e.engine_info:
                 e_uuid = e.engine_info['engineid']
                 eid = self._engines[e_uuid]
                 e.engine_info['engineid'] = eid
             self.results[msg_id] = e
     
     def _flush_notifications(self):
         """Flush notifications of engine registrations waiting
         in ZMQ queue."""
         msg = self.session.recv(self._notification_socket, mode=zmq.NOBLOCK)
         while msg is not None:
             if self.debug:
                 pprint(msg)
             msg = msg[-1]
             msg_type = msg['msg_type']
             handler = self._notification_handlers.get(msg_type, None)
             if handler is None:
                 raise Exception("Unhandled message type: %s"%msg.msg_type)
             else:
                 handler(msg)
             msg = self.session.recv(self._notification_socket, mode=zmq.NOBLOCK)
     
     def _flush_results(self, sock):
         """Flush task or queue results waiting in ZMQ queue."""
         msg = self.session.recv(sock, mode=zmq.NOBLOCK)
         while msg is not None:
             if self.debug:
                 pprint(msg)
             msg = msg[-1]
             msg_type = msg['msg_type']
             handler = self._queue_handlers.get(msg_type, None)
             if handler is None:
                 raise Exception("Unhandled message type: %s"%msg.msg_type)
             else:
                 handler(msg)
             msg = self.session.recv(sock, mode=zmq.NOBLOCK)
     
     def _flush_control(self, sock):
         """Flush replies from the control channel waiting
         in the ZMQ queue.
         
         Currently: ignore them."""
         msg = self.session.recv(sock, mode=zmq.NOBLOCK)
         while msg is not None:
             if self.debug:
                 pprint(msg)
             msg = self.session.recv(sock, mode=zmq.NOBLOCK)
     
     def _flush_iopub(self, sock):
         """Flush replies from the iopub channel waiting
         in the ZMQ queue.
         """
         msg = self.session.recv(sock, mode=zmq.NOBLOCK)
         while msg is not None:
             if self.debug:
                 pprint(msg)
             msg = msg[-1]
             parent = msg['parent_header']
             msg_id = parent['msg_id']
             content = msg['content']
             header = msg['header']
             msg_type = msg['msg_type']
             
             # init metadata:
             md = self.metadata.setdefault(msg_id, Metadata())
             
             if msg_type == 'stream':
                 name = content['name']
                 s = md[name] or ''
                 md[name] = s + content['data']
             elif msg_type == 'pyerr':
                 md.update({'pyerr' : ss.unwrap_exception(content)})
             else:
                 md.update({msg_type : content['data']})
             
             self.metadata[msg_id] = md
             
             msg = self.session.recv(sock, mode=zmq.NOBLOCK)
     
     #--------------------------------------------------------------------------
     # getitem
     #--------------------------------------------------------------------------
     
     def __getitem__(self, key):
-        """Dict access returns DirectView multiplexer objects or,
-        if key is None, a LoadBalancedView."""
-        if key is None:
-            return LoadBalancedView(self)
-        if isinstance(key, int):
-            if key not in self.ids:
-                raise IndexError("No such engine: %i"%key)
-            return DirectView(self, key)
-        
-        if isinstance(key, slice):
-            indices = range(len(self.ids))[key]
-            ids = sorted(self._ids)
-            key = [ ids[i] for i in indices ]
-            # newkeys = sorted(self._ids)[thekeys[k]]
+        """index access returns DirectView multiplexer objects
         
-        if isinstance(key, (tuple, list, xrange)):
-            _,targets = self._build_targets(list(key))
-            return DirectView(self, targets)
+        Must be int, slice, or list/tuple/xrange of ints"""
+        if not isinstance(key, (int, slice, tuple, list, xrange)):
+            raise TypeError("key by int/slice/iterable of ints only, not %s"%(type(key)))
         else:
-            raise TypeError("key by int/iterable of ints only, not %s"%(type(key)))
+            return self.view(key, balanced=False)
     
     #--------------------------------------------------------------------------
     # Begin public methods
     #--------------------------------------------------------------------------
     
-    @property
-    def remote(self):
-        """property for convenient RemoteFunction generation.
-        
-        >>> @client.remote
-        ... def getpid():
-                import os
-                return os.getpid()
-        """
-        return remote(self, block=self.block)
-    
     def spin(self):
         """Flush any registration notifications and execution results
         waiting in the ZMQ queue.
         """
         if self._notification_socket:
             self._flush_notifications()
         if self._mux_socket:
             self._flush_results(self._mux_socket)
         if self._task_socket:
             self._flush_results(self._task_socket)
         if self._control_socket:
             self._flush_control(self._control_socket)
         if self._iopub_socket:
             self._flush_iopub(self._iopub_socket)
     
     def barrier(self, msg_ids=None, timeout=-1):
         """waits on one or more `msg_ids`, for up to `timeout` seconds.
         
         Parameters
         ----------
+        
         msg_ids : int, str, or list of ints and/or strs, or one or more AsyncResult objects
                 ints are indices to self.history
                 strs are msg_ids
                 default: wait on all outstanding messages
         timeout : float
                 a time in seconds, after which to give up.
                 default is -1, which means no timeout
         
         Returns
         -------
+        
         True : when all msg_ids are done
         False : timeout reached, some msg_ids still outstanding
         """
         tic = time.time()
         if msg_ids is None:
             theids = self.outstanding
         else:
             if isinstance(msg_ids, (int, str, AsyncResult)):
                 msg_ids = [msg_ids]
             theids = set()
             for msg_id in msg_ids:
                 if isinstance(msg_id, int):
                     msg_id = self.history[msg_id]
                 elif isinstance(msg_id, AsyncResult):
                     map(theids.add, msg_id.msg_ids)
                     continue
                 theids.add(msg_id)
         if not theids.intersection(self.outstanding):
             return True
         self.spin()
         while theids.intersection(self.outstanding):
             if timeout >= 0 and ( time.time()-tic ) > timeout:
                 break
             time.sleep(1e-3)
             self.spin()
         return len(theids.intersection(self.outstanding)) == 0
     
     #--------------------------------------------------------------------------
     # Control methods
     #--------------------------------------------------------------------------
     
     @spinfirst
     @defaultblock
     def clear(self, targets=None, block=None):
         """Clear the namespace in target(s)."""
         targets = self._build_targets(targets)[0]
         for t in targets:
             self.session.send(self._control_socket, 'clear_request', content={}, ident=t)
         error = False
         if self.block:
             for i in range(len(targets)):
                 idents,msg = self.session.recv(self._control_socket,0)
                 if self.debug:
                     pprint(msg)
                 if msg['content']['status'] != 'ok':
                     error = ss.unwrap_exception(msg['content'])
         if error:
             return error
         
     
     @spinfirst
     @defaultblock
     def abort(self, msg_ids = None, targets=None, block=None):
         """Abort the execution queues of target(s)."""
         targets = self._build_targets(targets)[0]
         if isinstance(msg_ids, basestring):
             msg_ids = [msg_ids]
         content = dict(msg_ids=msg_ids)
         for t in targets:
             self.session.send(self._control_socket, 'abort_request', 
                     content=content, ident=t)
         error = False
         if self.block:
             for i in range(len(targets)):
                 idents,msg = self.session.recv(self._control_socket,0)
                 if self.debug:
                     pprint(msg)
                 if msg['content']['status'] != 'ok':
                     error = ss.unwrap_exception(msg['content'])
         if error:
             return error
     
     @spinfirst
     @defaultblock
     def shutdown(self, targets=None, restart=False, controller=False, block=None):
         """Terminates one or more engine processes, optionally including the controller."""
         if controller:
             targets = 'all'
         targets = self._build_targets(targets)[0]
         for t in targets:
             self.session.send(self._control_socket, 'shutdown_request', 
                         content={'restart':restart},ident=t)
         error = False
         if block or controller:
             for i in range(len(targets)):
                 idents,msg = self.session.recv(self._control_socket,0)
                 if self.debug:
                     pprint(msg)
                 if msg['content']['status'] != 'ok':
                     error = ss.unwrap_exception(msg['content'])
         
         if controller:
             time.sleep(0.25)
             self.session.send(self._query_socket, 'shutdown_request')
             idents,msg = self.session.recv(self._query_socket, 0)
             if self.debug:
                 pprint(msg)
             if msg['content']['status'] != 'ok':
                 error = ss.unwrap_exception(msg['content'])
         
         if error:
             raise error
     
     #--------------------------------------------------------------------------
     # Execution methods
     #--------------------------------------------------------------------------
     
     @defaultblock
     def execute(self, code, targets='all', block=None):
         """Executes `code` on `targets` in blocking or nonblocking manner.
         
         ``execute`` is always `bound` (affects engine namespace)
         
         Parameters
         ----------
+        
         code : str
                 the code string to be executed
         targets : int/str/list of ints/strs
                 the engines on which to execute
                 default : all
         block : bool
                 whether or not to wait until done to return
                 default: self.block
         """
-        result = self.apply(_execute, (code,), targets=targets, block=self.block, bound=True)
+        result = self.apply(_execute, (code,), targets=targets, block=self.block, bound=True, balanced=False)
         return result
     
     def run(self, filename, targets='all', block=None):
         """Execute contents of `filename` on engine(s). 
         
         This simply reads the contents of the file and calls `execute`.
         
         Parameters
         ----------
+        
         filename : str
                 The path to the file
         targets : int/str/list of ints/strs
                 the engines on which to execute
                 default : all
         block : bool
                 whether or not to wait until done
                 default: self.block
         
         """
         with open(filename, 'rb') as f:
             code = f.read()
         return self.execute(code, targets=targets, block=block)
     
     def _maybe_raise(self, result):
         """wrapper for maybe raising an exception if apply failed."""
         if isinstance(result, error.RemoteError):
             raise result
         
         return result
     
     def _build_dependency(self, dep):
         """helper for building jsonable dependencies from various input forms"""
         if isinstance(dep, Dependency):
             return dep.as_dict()
         elif isinstance(dep, AsyncResult):
             return dep.msg_ids
         elif dep is None:
             return []
         else:
             # pass to Dependency constructor
             return list(Dependency(dep))
         
     @defaultblock
-    def apply(self, f, args=None, kwargs=None, bound=True, block=None, targets=None,
+    def apply(self, f, args=None, kwargs=None, bound=True, block=None,
+                        targets=None, balanced=None,
                         after=None, follow=None, timeout=None):
         """Call `f(*args, **kwargs)` on a remote engine(s), returning the result.
         
         This is the central execution command for the client.
         
         Parameters
         ----------
         
         f : function
             The fuction to be called remotely
         args : tuple/list
             The positional arguments passed to `f`
         kwargs : dict
             The keyword arguments passed to `f`
         bound : bool (default: True)
             Whether to execute in the Engine(s) namespace, or in a clean
             namespace not affecting the engine.
         block : bool (default: self.block)
             Whether to wait for the result, or return immediately.
             False:
                 returns AsyncResult
             True:
                 returns actual result(s) of f(*args, **kwargs)
                 if multiple targets:
                     list of results, matching `targets`
         targets : int,list of ints, 'all', None
             Specify the destination of the job.
             if None:
                 Submit via Task queue for load-balancing.
             if 'all':
                 Run on all active engines
             if list:
                 Run on each specified engine
             if int:
                 Run on single engine
         
-        after,follow,timeout only used in `apply_balanced`. See that docstring
-        for details.
+        balanced : bool, default None
+            whether to load-balance.  This will default to True
+            if targets is unspecified, or False if targets is specified.
+            
+            The following arguments are only used when balanced is True:
+        after : Dependency or collection of msg_ids
+            Only for load-balanced execution (targets=None)
+            Specify a list of msg_ids as a time-based dependency.
+            This job will only be run *after* the dependencies
+            have been met.
+            
+        follow : Dependency or collection of msg_ids
+            Only for load-balanced execution (targets=None)
+            Specify a list of msg_ids as a location-based dependency.
+            This job will only be run on an engine where this dependency
+            is met.
+        
+        timeout : float/int or None
+            Only for load-balanced execution (targets=None)
+            Specify an amount of time (in seconds) for the scheduler to
+            wait for dependencies to be met before failing with a
+            DependencyTimeout.
+        
+        after,follow,timeout only used if `balanced=True`.
         
         Returns
         -------
+        
         if block is False:
             return AsyncResult wrapping msg_ids
             output of AsyncResult.get() is identical to that of `apply(...block=True)`
         else:
             if single target:
                 return result of `f(*args, **kwargs)`
             else:
                 return list of results, matching `targets`
         """
         
         # defaults:
-        block = block if block is not None else self.block
         args = args if args is not None else []
         kwargs = kwargs if kwargs is not None else {}
         
+        if balanced is None:
+            if targets is None:
+                # default to balanced if targets unspecified
+                balanced = True
+            else:
+                # otherwise default to multiplexing
+                balanced = False
+        
+        if targets is None and balanced is False:
+            # default to all if *not* balanced, and targets is unspecified
+            targets = 'all'
+        
         # enforce types of f,args,kwrags
         if not callable(f):
             raise TypeError("f must be callable, not %s"%type(f))
         if not isinstance(args, (tuple, list)):
             raise TypeError("args must be tuple or list, not %s"%type(args))
         if not isinstance(kwargs, dict):
             raise TypeError("kwargs must be dict, not %s"%type(kwargs))
         
         options  = dict(bound=bound, block=block, targets=targets)
             
-        if targets is None:
-            return self.apply_balanced(f, args, kwargs, timeout=timeout, 
+        if balanced:
+            return self._apply_balanced(f, args, kwargs, timeout=timeout, 
                                         after=after, follow=follow, **options)
-        else:
-            if follow or after or timeout:
-                msg = "follow, after, and timeout args are only used for load-balanced"
-                msg += "execution."
+        elif follow or after or timeout:
+                msg = "follow, after, and timeout args are only used for"
+                msg += " load-balanced execution."
                 raise ValueError(msg)
+        else:
             return self._apply_direct(f, args, kwargs, **options)
     
-    @defaultblock
-    def apply_balanced(self, f, args, kwargs, bound=True, block=None, targets=None,
+    def _apply_balanced(self, f, args, kwargs, bound=True, block=None, targets=None,
                             after=None, follow=None, timeout=None):
         """call f(*args, **kwargs) remotely in a load-balanced manner.
         
-        Parameters
-        ----------
-        
-        f : function
-            The fuction to be called remotely
-        args : tuple/list
-            The positional arguments passed to `f`
-        kwargs : dict
-            The keyword arguments passed to `f`
-        bound : bool (default: True)
-            Whether to execute in the Engine(s) namespace, or in a clean
-            namespace not affecting the engine.
-        block : bool (default: self.block)
-            Whether to wait for the result, or return immediately.
-            False:
-                returns AsyncResult
-            True:
-                returns actual result(s) of f(*args, **kwargs)
-                if multiple targets:
-                    list of results, matching `targets`
-        targets : int,list of ints, 'all', None
-            Specify the destination of the job.
-            if None:
-                Submit via Task queue for load-balancing.
-            if 'all':
-                Run on all active engines
-            if list:
-                Run on each specified engine
-            if int:
-                Run on single engine
-        
-        after : Dependency or collection of msg_ids
-            Only for load-balanced execution (targets=None)
-            Specify a list of msg_ids as a time-based dependency.
-            This job will only be run *after* the dependencies
-            have been met.
-            
-        follow : Dependency or collection of msg_ids
-            Only for load-balanced execution (targets=None)
-            Specify a list of msg_ids as a location-based dependency.
-            This job will only be run on an engine where this dependency
-            is met.
-        
-        timeout : float/int or None
-            Only for load-balanced execution (targets=None)
-            Specify an amount of time (in seconds) for the scheduler to
-            wait for dependencies to be met before failing with a
-            DependencyTimeout.
-        
-        Returns
-        -------
-        if block is False:
-            return AsyncResult wrapping msg_id
-            output of AsyncResult.get() is identical to that of `apply(...block=True)`
-        else:
-            wait for, and return actual result of `f(*args, **kwargs)`
-        
+        This is a private method, see `apply` for details.
+        Not to be called directly!
         """
         
+        for kwarg in (bound, block, targets):
+            assert kwarg is not None, "kwarg %r must be specified!"%kwarg
+        
         if self._task_socket is None:
             msg = "Task farming is disabled"
             if self._task_scheme == 'pure':
                 msg += " because the pure ZMQ scheduler cannot handle"
                 msg += " disappearing engines."
             raise RuntimeError(msg)
         
         if self._task_scheme == 'pure':
             # pure zmq scheme doesn't support dependencies
             msg = "Pure ZMQ scheduler doesn't support dependencies"
             if (follow or after):
                 # hard fail on DAG dependencies
                 raise RuntimeError(msg)
             if isinstance(f, dependent):
                 # soft warn on functional dependencies
                 warnings.warn(msg, RuntimeWarning)
-            
         
         # defaults:
         args = args if args is not None else []
         kwargs = kwargs if kwargs is not None else {}
         
         if targets:
             idents,_ = self._build_targets(targets)
         else:
             idents = []
         
-        # enforce types of f,args,kwrags
-        if not callable(f):
-            raise TypeError("f must be callable, not %s"%type(f))
-        if not isinstance(args, (tuple, list)):
-            raise TypeError("args must be tuple or list, not %s"%type(args))
-        if not isinstance(kwargs, dict):
-            raise TypeError("kwargs must be dict, not %s"%type(kwargs))
-        
         after = self._build_dependency(after)
         follow = self._build_dependency(follow)
         subheader = dict(after=after, follow=follow, timeout=timeout, targets=idents)
         bufs = ss.pack_apply_message(f,args,kwargs)
         content = dict(bound=bound)
         
         msg = self.session.send(self._task_socket, "apply_request", 
                 content=content, buffers=bufs, subheader=subheader)
         msg_id = msg['msg_id']
         self.outstanding.add(msg_id)
         self.history.append(msg_id)
         ar = AsyncResult(self, [msg_id], fname=f.__name__)
         if block:
             try:
                 return ar.get()
             except KeyboardInterrupt:
                 return ar
         else:
             return ar
     
-    def _apply_direct(self, f, args, kwargs, bound=True, block=None, targets=None):
+    def _apply_direct(self, f, args, kwargs, bound=None, block=None, targets=None):
         """Then underlying method for applying functions to specific engines
         via the MUX queue.
         
+        This is a private method, see `apply` for details.
         Not to be called directly!
         """
         
+        for kwarg in (bound, block, targets):
+            assert kwarg is not None, "kwarg %r must be specified!"%kwarg
+        
         idents,targets = self._build_targets(targets)
         
         subheader = {}
         content = dict(bound=bound)
         bufs = ss.pack_apply_message(f,args,kwargs)
         
         msg_ids = []
         for ident in idents:
             msg = self.session.send(self._mux_socket, "apply_request", 
                     content=content, buffers=bufs, ident=ident, subheader=subheader)
             msg_id = msg['msg_id']
             self.outstanding.add(msg_id)
             self.history.append(msg_id)
             msg_ids.append(msg_id)
         ar = AsyncResult(self, msg_ids, fname=f.__name__)
         if block:
             try:
                 return ar.get()
             except KeyboardInterrupt:
                 return ar
         else:
             return ar
     
     #--------------------------------------------------------------------------
-    # Map and decorators
+    # decorators
     #--------------------------------------------------------------------------
     
-    def map(self, f, *sequences, **kwargs):
-        """Parallel version of builtin `map`, using all our engines.
-        
-        `block` and `targets` can be passed as keyword arguments only.
-        
-        There will be one task per target, so work will be chunked
-        if the sequences are longer than `targets`.  
-        
-        Results can be iterated as they are ready, but will become available in chunks.
-        
-        Parameters
-        ----------
-        
-        f : callable
-            function to be mapped
-        *sequences: one or more sequences of matching length
-            the sequences to be distributed and passed to `f`
-        block : bool
-            whether to wait for the result or not [default self.block]
-        targets : valid targets
-            targets to be used [default self.targets]
-        
-        Returns
-        -------
-        
-        if block=False:
-            AsyncMapResult
-                An object like AsyncResult, but which reassembles the sequence of results
-                into a single list. AsyncMapResults can be iterated through before all
-                results are complete.
-            else:
-                the result of map(f,*sequences)
-        
-        """
-        block = kwargs.get('block', self.block)
-        targets = kwargs.get('targets', self.targets)
-        assert len(sequences) > 0, "must have some sequences to map onto!"
-        pf = ParallelFunction(self, f, block=block,
-                        bound=True, targets=targets)
-        return pf.map(*sequences)
-    
-    def imap(self, f, *sequences, **kwargs):
-        """Parallel version of builtin `itertools.imap`, load-balanced across all engines.
-        
-        Each element will be a separate task, and will be load-balanced.  This
-        lets individual elements be ready for iteration as soon as they come.
-        
-        Parameters
-        ----------
-        
-        f : callable
-            function to be mapped
-        *sequences: one or more sequences of matching length
-            the sequences to be distributed and passed to `f`
-        block : bool
-            whether to wait for the result or not [default self.block]
-        
-        Returns
-        -------
-        
-        if block=False:
-            AsyncMapResult
-                An object like AsyncResult, but which reassembles the sequence of results
-                into a single list. AsyncMapResults can be iterated through before all
-                results are complete.
-            else:
-                the result of map(f,*sequences)
-        
-        """
-        
-        block = kwargs.get('block', self.block)
-        
-        assert len(sequences) > 0, "must have some sequences to map onto!"
-        
-        pf = ParallelFunction(self, f, block=self.block,
-                        bound=True, targets=None)
-        return pf.map(*sequences)
-    
-    def parallel(self, bound=True, targets='all', block=True):
+    @defaultblock
+    def parallel(self, bound=True, targets='all', block=None):
         """Decorator for making a ParallelFunction."""
         return parallel(self, bound=bound, targets=targets, block=block)
     
-    def remote(self, bound=True, targets='all', block=True):
+    @defaultblock
+    def remote(self, bound=True, targets='all', block=None):
         """Decorator for making a RemoteFunction."""
         return remote(self, bound=bound, targets=targets, block=block)
     
     def view(self, targets=None, balanced=False):
         """Method for constructing View objects"""
-        if not balanced:
-            if not targets:
+        if targets is None:
+            if balanced:
+                return LoadBalancedView(client=self)
+            else:
                 targets = slice(None)
-            return self[targets]
+        
+        if balanced:
+            view_class = LoadBalancedView
+        else:
+            view_class = DirectView
+        if isinstance(targets, int):
+            if targets not in self.ids:
+                raise IndexError("No such engine: %i"%targets)
+            return view_class(client=self, targets=targets)
+        
+        if isinstance(targets, slice):
+            indices = range(len(self.ids))[targets]
+            ids = sorted(self._ids)
+            targets = [ ids[i] for i in indices ]
+        
+        if isinstance(targets, (tuple, list, xrange)):
+            _,targets = self._build_targets(list(targets))
+            return view_class(client=self, targets=targets)
         else:
-            return LoadBalancedView(self, targets)
+            raise TypeError("targets by int/slice/collection of ints only, not %s"%(type(targets)))
     
     #--------------------------------------------------------------------------
     # Data movement
     #--------------------------------------------------------------------------
     
     @defaultblock
     def push(self, ns, targets='all', block=None):
         """Push the contents of `ns` into the namespace on `target`"""
         if not isinstance(ns, dict):
             raise TypeError("Must be a dict, not %s"%type(ns))
-        result = self.apply(_push, (ns,), targets=targets, block=block, bound=True)
+        result = self.apply(_push, (ns,), targets=targets, block=block, bound=True, balanced=False)
         return result
     
     @defaultblock
     def pull(self, keys, targets='all', block=None):
         """Pull objects from `target`'s namespace by `keys`"""
         if isinstance(keys, str):
             pass
         elif isinstance(keys, (list,tuple,set)):
             for key in keys:
                 if not isinstance(key, str):
                     raise TypeError
-        result = self.apply(_pull, (keys,), targets=targets, block=block, bound=True)
+        result = self.apply(_pull, (keys,), targets=targets, block=block, bound=True, balanced=False)
         return result
     
+    @defaultblock
     def scatter(self, key, seq, dist='b', flatten=False, targets='all', block=None):
         """
         Partition a Python sequence and send the partitions to a set of engines.
         """
-        block = block if block is not None else self.block
         targets = self._build_targets(targets)[-1]
         mapObject = Map.dists[dist]()
         nparts = len(targets)
         msg_ids = []
         for index, engineid in enumerate(targets):
             partition = mapObject.getPartition(seq, index, nparts)
             if flatten and len(partition) == 1:
                 r = self.push({key: partition[0]}, targets=engineid, block=False)
             else:
                 r = self.push({key: partition}, targets=engineid, block=False)
             msg_ids.extend(r.msg_ids)
         r = AsyncResult(self, msg_ids, fname='scatter')
         if block:
             return r.get()
         else:
             return r
     
+    @defaultblock
     def gather(self, key, dist='b', targets='all', block=None):
         """
         Gather a partitioned sequence on a set of engines as a single local seq.
         """
-        block = block if block is not None else self.block
         
         targets = self._build_targets(targets)[-1]
         mapObject = Map.dists[dist]()
         msg_ids = []
         for index, engineid in enumerate(targets):
             msg_ids.extend(self.pull(key, targets=engineid,block=False).msg_ids)
         
         r = AsyncMapResult(self, msg_ids, mapObject, fname='gather')
         if block:
             return r.get()
         else:
             return r
     
     #--------------------------------------------------------------------------
     # Query methods
     #--------------------------------------------------------------------------
     
     @spinfirst
     def get_results(self, msg_ids, status_only=False):
         """Returns the result of the execute or task request with `msg_ids`.
         
         Parameters
         ----------
+        
         msg_ids : list of ints or msg_ids
             if int:
                 Passed as index to self.history for convenience.
         status_only : bool (default: False)
             if False:
                 return the actual results
         
         Returns
         -------
         
         results : dict
             There will always be the keys 'pending' and 'completed', which will
             be lists of msg_ids.
         """
         if not isinstance(msg_ids, (list,tuple)):
             msg_ids = [msg_ids]
         theids = []
         for msg_id in msg_ids:
             if isinstance(msg_id, int):
                 msg_id = self.history[msg_id]
             if not isinstance(msg_id, str):
                 raise TypeError("msg_ids must be str, not %r"%msg_id)
             theids.append(msg_id)
         
         completed = []
         local_results = {}
         
         # comment this block out to temporarily disable local shortcut:
         for msg_id in list(theids):
             if msg_id in self.results:
                 completed.append(msg_id)
                 local_results[msg_id] = self.results[msg_id]
                 theids.remove(msg_id)
         
         if theids: # some not locally cached
             content = dict(msg_ids=theids, status_only=status_only)
             msg = self.session.send(self._query_socket, "result_request", content=content)
             zmq.select([self._query_socket], [], [])
             idents,msg = self.session.recv(self._query_socket, zmq.NOBLOCK)
             if self.debug:
                 pprint(msg)
             content = msg['content']
             if content['status'] != 'ok':
                 raise ss.unwrap_exception(content)
             buffers = msg['buffers']
         else:
             content = dict(completed=[],pending=[])
         
         content['completed'].extend(completed)
         
         if status_only:
             return content
         
         failures = []
         # load cached results into result:
         content.update(local_results)
         # update cache with results:
         for msg_id in sorted(theids):
             if msg_id in content['completed']:
                 rec = content[msg_id]
                 parent = rec['header']
                 header = rec['result_header']
                 rcontent = rec['result_content']
                 iodict = rec['io']
                 if isinstance(rcontent, str):
                     rcontent = self.session.unpack(rcontent)
                 
                 md = self.metadata.setdefault(msg_id, Metadata())
                 md.update(self._extract_metadata(header, parent, rcontent))
                 md.update(iodict)
                 
                 if rcontent['status'] == 'ok':
                     res,buffers = ss.unserialize_object(buffers)
                 else:
                     res = ss.unwrap_exception(rcontent)
                     failures.append(res)
                 
                 self.results[msg_id] = res
                 content[msg_id] = res
         
         error.collect_exceptions(failures, "get_results")
         return content
 
     @spinfirst
-    def queue_status(self, targets=None, verbose=False):
+    def queue_status(self, targets='all', verbose=False):
         """Fetch the status of engine queues.
         
         Parameters
         ----------
+        
         targets : int/str/list of ints/strs
-                the engines on which to execute
+                the engines whose states are to be queried.
                 default : all
         verbose : bool
                 Whether to return lengths only, or lists of ids for each element
         """
         targets = self._build_targets(targets)[1]
         content = dict(targets=targets, verbose=verbose)
         self.session.send(self._query_socket, "queue_request", content=content)
         idents,msg = self.session.recv(self._query_socket, 0)
         if self.debug:
             pprint(msg)
         content = msg['content']
         status = content.pop('status')
         if status != 'ok':
             raise ss.unwrap_exception(content)
         return ss.rekey(content)
         
     @spinfirst
     def purge_results(self, msg_ids=[], targets=[]):
         """Tell the controller to forget results.
         
         Individual results can be purged by msg_id, or the entire
         history of specific targets can be purged.
         
         Parameters
         ----------
+        
         msg_ids : str or list of strs
                 the msg_ids whose results should be forgotten.
         targets : int/str/list of ints/strs
                 The targets, by uuid or int_id, whose entire history is to be purged.
                 Use `targets='all'` to scrub everything from the controller's memory.
                 
                 default : None
         """
         if not targets and not msg_ids:
             raise ValueError
         if targets:
             targets = self._build_targets(targets)[1]
         content = dict(targets=targets, msg_ids=msg_ids)
         self.session.send(self._query_socket, "purge_request", content=content)
         idents, msg = self.session.recv(self._query_socket, 0)
         if self.debug:
             pprint(msg)
         content = msg['content']
         if content['status'] != 'ok':
             raise ss.unwrap_exception(content)
 
-    #----------------------------------------
-    # activate for %px,%autopx magics
-    #----------------------------------------
-    def activate(self):
-        """Make this `View` active for parallel magic commands.
-        
-        IPython has a magic command syntax to work with `MultiEngineClient` objects.
-        In a given IPython session there is a single active one.  While
-        there can be many `Views` created and used by the user, 
-        there is only one active one.  The active `View` is used whenever 
-        the magic commands %px and %autopx are used.
-        
-        The activate() method is called on a given `View` to make it 
-        active.  Once this has been done, the magic commands can be used.
-        """
-        
-        try:
-            # This is injected into __builtins__.
-            ip = get_ipython()
-        except NameError:
-            print "The IPython parallel magics (%result, %px, %autopx) only work within IPython."
-        else:
-            pmagic = ip.plugin_manager.get_plugin('parallelmagic')
-            if pmagic is not None:
-                pmagic.active_multiengine_client = self
-            else:
-                print "You must first load the parallelmagic extension " \
-                      "by doing '%load_ext parallelmagic'"
-
-class AsynClient(Client):
-    """An Asynchronous client, using the Tornado Event Loop.
-    !!!unfinished!!!"""
-    io_loop = None
-    _queue_stream = None
-    _notifier_stream = None
-    _task_stream = None
-    _control_stream = None
-    
-    def __init__(self, addr, context=None, username=None, debug=False, io_loop=None):
-        Client.__init__(self, addr, context, username, debug)
-        if io_loop is None:
-            io_loop = ioloop.IOLoop.instance()
-        self.io_loop = io_loop
-        
-        self._queue_stream = zmqstream.ZMQStream(self._mux_socket, io_loop)
-        self._control_stream = zmqstream.ZMQStream(self._control_socket, io_loop)
-        self._task_stream = zmqstream.ZMQStream(self._task_socket, io_loop)
-        self._notification_stream = zmqstream.ZMQStream(self._notification_socket, io_loop)
-    
-    def spin(self):
-        for stream in (self.queue_stream, self.notifier_stream, 
-                        self.task_stream, self.control_stream):
-            stream.flush()
 
 __all__ = [ 'Client', 
             'depend', 
             'require', 
             'remote',
             'parallel',
             'RemoteFunction',
             'ParallelFunction',
             'DirectView',
             'LoadBalancedView',
             'AsyncResult',
             'AsyncMapResult'
             ]

IPython/zmq/parallel/remotefunction.py

@@ -1,145 +1,156 b''
 """Remote Functions and decorators for the client."""
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  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 map as Map
 from asyncresult import AsyncMapResult
 
 #-----------------------------------------------------------------------------
 # Decorators
 #-----------------------------------------------------------------------------
 
-def remote(client, bound=False, block=None, targets=None):
+def remote(client, bound=False, block=None, targets=None, balanced=None):
     """Turn a function into a remote function.
     
     This method can be used for map:
     
     >>> @remote(client,block=True)
         def func(a)
     """
     def remote_function(f):
-        return RemoteFunction(client, f, bound, block, targets)
+        return RemoteFunction(client, f, bound, block, targets, balanced)
     return remote_function
 
-def parallel(client, dist='b', bound=False, block=None, targets='all'):
+def parallel(client, dist='b', bound=False, block=None, targets='all', balanced=None):
     """Turn a function into a parallel remote function.
     
     This method can be used for map:
     
     >>> @parallel(client,block=True)
         def func(a)
     """
     def parallel_function(f):
-        return ParallelFunction(client, f, dist, bound, block, targets)
+        return ParallelFunction(client, f, dist, bound, block, targets, balanced)
     return parallel_function
 
 #--------------------------------------------------------------------------
 # Classes
 #--------------------------------------------------------------------------
 
 class RemoteFunction(object):
     """Turn an existing function into a remote function.
     
     Parameters
     ----------
     
     client : Client instance
         The client to be used to connect to engines
     f : callable
         The function to be wrapped into a remote function
     bound : bool [default: False]
         Whether the affect the remote namespace when called
     block : bool [default: None]
         Whether to wait for results or not.  The default behavior is
         to use the current `block` attribute of `client`
     targets : valid target list [default: all]
         The targets on which to execute.
+    balanced : bool
+        Whether to load-balance with the Task scheduler or not
     """
     
     client = None # the remote connection
     func = None # the wrapped function
     block = None # whether to block
     bound = None # whether to affect the namespace
     targets = None # where to execute
+    balanced = None # whether to load-balance
     
-    def __init__(self, client, f, bound=False, block=None, targets=None):
+    def __init__(self, client, f, bound=False, block=None, targets=None, balanced=None):
         self.client = client
         self.func = f
         self.block=block
         self.bound=bound
         self.targets=targets
+        if balanced is None:
+            if targets is None:
+                balanced = True
+            else:
+                balanced = False
+        self.balanced = balanced
     
     def __call__(self, *args, **kwargs):
         return self.client.apply(self.func, args=args, kwargs=kwargs,
-                block=self.block, targets=self.targets, bound=self.bound)
+                block=self.block, targets=self.targets, bound=self.bound, balanced=self.balanced)
     
 
 class ParallelFunction(RemoteFunction):
     """Class for mapping a function to sequences."""
-    def __init__(self, client, f, dist='b', bound=False, block=None, targets='all'):
-        super(ParallelFunction, self).__init__(client,f,bound,block,targets)
+    def __init__(self, client, f, dist='b', bound=False, block=None, targets='all', balanced=None):
+        super(ParallelFunction, self).__init__(client,f,bound,block,targets,balanced)
         mapClass = Map.dists[dist]
         self.mapObject = mapClass()
     
     def __call__(self, *sequences):
         len_0 = len(sequences[0])
         for s in sequences:
             if len(s)!=len_0:
-                raise ValueError('all sequences must have equal length')
+                msg = 'all sequences must have equal length, but %i!=%i'%(len_0,len(s))
+                raise ValueError(msg)
         
-        if self.targets is None:
-            # load-balanced:
-            engines = [None]*len_0
-        elif isinstance(self.targets, int):
-            engines = [None]*self.targets
+        if self.balanced:
+            targets = [self.targets]*len_0
         else:
             # multiplexed:
-            engines = self.client._build_targets(self.targets)[-1]
+            targets = self.client._build_targets(self.targets)[-1]
         
-        nparts = len(engines)
+        nparts = len(targets)
         msg_ids = []
         # my_f = lambda *a: map(self.func, *a)
-        for index, engineid in enumerate(engines):
+        for index, t in enumerate(targets):
             args = []
             for seq in sequences:
                 part = self.mapObject.getPartition(seq, index, nparts)
                 if not part:
                     continue
                 else:
                     args.append(part)
             if not args:
                 continue
             
             # print (args)
             if hasattr(self, '_map'):
                 f = map
                 args = [self.func]+args
             else:
                 f=self.func
-            mid = self.client.apply(f, args=args, block=False, 
-                        bound=self.bound,
-                        targets=engineid).msg_ids[0]
-            msg_ids.append(mid)
+            ar = self.client.apply(f, args=args, block=False, bound=self.bound, 
+                        targets=targets, balanced=self.balanced)
+            
+            msg_ids.append(ar.msg_ids[0])
         
         r = AsyncMapResult(self.client, msg_ids, self.mapObject, fname=self.func.__name__)
         if self.block:
-            r.wait()
-            return r.result
+            try:
+                return r.get()
+            except KeyboardInterrupt:
+                return r
         else:
             return r
     
     def map(self, *sequences):
         """call a function on each element of a sequence remotely."""
         self._map = True
-        ret = self.__call__(*sequences)
-        del self._map
+        try:
+            ret = self.__call__(*sequences)
+        finally:
+            del self._map
         return ret
 

IPython/zmq/parallel/util.py

@@ -1,119 +1,119 b''
 """some generic utilities"""
 import re
 import socket
 
 class ReverseDict(dict):
     """simple double-keyed subset of dict methods."""
     
     def __init__(self, *args, **kwargs):
         dict.__init__(self, *args, **kwargs)
         self._reverse = dict()
         for key, value in self.iteritems():
             self._reverse[value] = key
     
     def __getitem__(self, key):
         try:
             return dict.__getitem__(self, key)
         except KeyError:
             return self._reverse[key]
     
     def __setitem__(self, key, value):
         if key in self._reverse:
             raise KeyError("Can't have key %r on both sides!"%key)
         dict.__setitem__(self, key, value)
         self._reverse[value] = key
     
     def pop(self, key):
         value = dict.pop(self, key)
         self._reverse.pop(value)
         return value
     
     def get(self, key, default=None):
         try:
             return self[key]
         except KeyError:
             return default
     
 
 def validate_url(url):
     """validate a url for zeromq"""
     if not isinstance(url, basestring):
         raise TypeError("url must be a string, not %r"%type(url))
     url = url.lower()
     
     proto_addr = url.split('://')
     assert len(proto_addr) == 2, 'Invalid url: %r'%url
     proto, addr = proto_addr
     assert proto in ['tcp','pgm','epgm','ipc','inproc'], "Invalid protocol: %r"%proto
     
     # domain pattern adapted from http://www.regexlib.com/REDetails.aspx?regexp_id=391
     # author: Remi Sabourin
     pat = re.compile(r'^([\w\d]([\w\d\-]{0,61}[\w\d])?\.)*[\w\d]([\w\d\-]{0,61}[\w\d])?$')
     
     if proto == 'tcp':
         lis = addr.split(':')
         assert len(lis) == 2, 'Invalid url: %r'%url
         addr,s_port = lis
         try:
             port = int(s_port)
         except ValueError:
             raise AssertionError("Invalid port %r in url: %r"%(port, url))
         
-        assert pat.match(addr) is not None, 'Invalid url: %r'%url
+        assert addr == '*' or pat.match(addr) is not None, 'Invalid url: %r'%url
         
     else:
         # only validate tcp urls currently
         pass
     
     return True
 
 
 def validate_url_container(container):
     """validate a potentially nested collection of urls."""
     if isinstance(container, basestring):
         url = container
         return validate_url(url)
     elif isinstance(container, dict):
         container = container.itervalues()
     
     for element in container:
         validate_url_container(element)
 
 
 def split_url(url):
     """split a zmq url (tcp://ip:port) into ('tcp','ip','port')."""
     proto_addr = url.split('://')
     assert len(proto_addr) == 2, 'Invalid url: %r'%url
     proto, addr = proto_addr
     lis = addr.split(':')
     assert len(lis) == 2, 'Invalid url: %r'%url
     addr,s_port = lis
     return proto,addr,s_port
     
 def disambiguate_ip_address(ip, location=None):
     """turn multi-ip interfaces '0.0.0.0' and '*' into connectable
     ones, based on the location (default interpretation of location is localhost)."""
     if ip in ('0.0.0.0', '*'):
         external_ips = socket.gethostbyname_ex(socket.gethostname())[2]
         if location is None or location in external_ips:
             ip='127.0.0.1'
         elif location:
             return location
     return ip
 
 def disambiguate_url(url, location=None):
     """turn multi-ip interfaces '0.0.0.0' and '*' into connectable
     ones, based on the location (default interpretation is localhost).
     
     This is for zeromq urls, such as tcp://*:10101."""
     try:
         proto,ip,port = split_url(url)
     except AssertionError:
         # probably not tcp url; could be ipc, etc.
         return url
     
     ip = disambiguate_ip_address(ip,location)
     
     return "%s://%s:%s"%(proto,ip,port)
 
 

IPython/zmq/parallel/view.py

@@ -1,383 +1,572 b''
 """Views of remote engines"""
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  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
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import HasTraits, Bool, List, Dict, Set, Int, Instance
+
 from IPython.external.decorator import decorator
+from IPython.zmq.parallel.asyncresult import AsyncResult
+from IPython.zmq.parallel.dependency import Dependency
 from IPython.zmq.parallel.remotefunction import ParallelFunction, parallel
 
 #-----------------------------------------------------------------------------
 # Decorators
 #-----------------------------------------------------------------------------
 
 @decorator
 def myblock(f, self, *args, **kwargs):
     """override client.block with self.block during a call"""
     block = self.client.block
     self.client.block = self.block
     try:
         ret = f(self, *args, **kwargs)
     finally:
         self.client.block = block
     return ret
 
 @decorator
 def save_ids(f, self, *args, **kwargs):
     """Keep our history and outstanding attributes up to date after a method call."""
     n_previous = len(self.client.history)
     ret = f(self, *args, **kwargs)
     nmsgs = len(self.client.history) - n_previous
     msg_ids = self.client.history[-nmsgs:]
     self.history.extend(msg_ids)
     map(self.outstanding.add, msg_ids)
     return ret
 
 @decorator
 def sync_results(f, self, *args, **kwargs):
     """sync relevant results from self.client to our results attribute."""
     ret = f(self, *args, **kwargs)
     delta = self.outstanding.difference(self.client.outstanding)
     completed = self.outstanding.intersection(delta)
     self.outstanding = self.outstanding.difference(completed)
     for msg_id in completed:
         self.results[msg_id] = self.client.results[msg_id]
     return ret
 
 @decorator
 def spin_after(f, self, *args, **kwargs):
     """call spin after the method."""
     ret = f(self, *args, **kwargs)
     self.spin()
     return ret
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
-class View(object):
+class View(HasTraits):
     """Base View class for more convenint apply(f,*args,**kwargs) syntax via attributes.
     
     Don't use this class, use subclasses.
     """
-    block=None
-    bound=None
-    history=None
-    outstanding = set()
-    results = {}
-    
+    block=Bool(False)
+    bound=Bool(False)
+    history=List()
+    outstanding = Set()
+    results = Dict()
+    client = Instance('IPython.zmq.parallel.client.Client')
+    
+    _ntargets = Int(1)
+    _balanced = Bool(False)
+    _default_names = List(['block', 'bound'])
     _targets = None
-    _apply_name = 'apply'
-    _default_names = ['targets', 'block']
     
-    def __init__(self, client, targets=None):
-        self.client = client
+    def __init__(self, client=None, targets=None):
+        super(View, self).__init__(client=client)
         self._targets = targets
         self._ntargets = 1 if isinstance(targets, (int,type(None))) else len(targets)
         self.block = client.block
-        self.bound=False
-        self.history = []
-        self.outstanding = set()
-        self.results = {}
+        
         for name in self._default_names:
             setattr(self, name, getattr(self, name, None))
         
 
     def __repr__(self):
         strtargets = str(self._targets)
         if len(strtargets) > 16:
             strtargets = strtargets[:12]+'...]'
         return "<%s %s>"%(self.__class__.__name__, strtargets)
 
     @property
     def targets(self):
         return self._targets
 
     @targets.setter
     def targets(self, value):
-        self._targets = value
-        # raise AttributeError("Cannot set my targets argument after construction!")
+        raise AttributeError("Cannot set View `targets` after construction!")
     
     def _defaults(self, *excludes):
         """return dict of our default attributes, excluding names given."""
-        d = {}
+        d = dict(balanced=self._balanced, targets=self.targets)
         for name in self._default_names:
             if name not in excludes:
                 d[name] = getattr(self, name)
         return d
     
+    def set_flags(self, **kwargs):
+        """set my attribute flags by keyword.
+        
+        A View is a wrapper for the Client's apply method, but
+        with attributes that specify keyword arguments, those attributes
+        can be set by keyword argument with this method.
+        
+        Parameters
+        ----------
+        
+        block : bool
+            whether to wait for results
+        bound : bool
+            whether to use the client's namespace
+        """
+        for key in kwargs:
+            if key not in self._default_names:
+                raise KeyError("Invalid name: %r"%key)
+        for name in ('block', 'bound'):
+            if name in kwargs:
+                setattr(self, name, kwargs)
+    
+    #----------------------------------------------------------------
+    # wrappers for client methods:
+    #----------------------------------------------------------------
     @sync_results
     def spin(self):
         """spin the client, and sync"""
         self.client.spin()
     
-    @property
-    def _apply(self):
-        return getattr(self.client, self._apply_name)
-
     @sync_results
     @save_ids
     def apply(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) on remote engines, returning the result.
         
         This method does not involve the engine's namespace.
         
         if self.block is False:
             returns msg_id
         else:
             returns actual result of f(*args, **kwargs)
         """
-        return self._apply(f, args, kwargs, **self._defaults())
+        return self.client.apply(f, args, kwargs, **self._defaults())
 
     @save_ids
     def apply_async(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) on remote engines in a nonblocking manner.
         
         This method does not involve the engine's namespace.
         
         returns msg_id
         """
         d = self._defaults('block', 'bound')
-        return self._apply(f,args,kwargs, block=False, bound=False, **d)
+        return self.client.apply(f,args,kwargs, block=False, bound=False, **d)
 
     @spin_after
     @save_ids
     def apply_sync(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) on remote engines in a blocking manner,
          returning the result.
         
         This method does not involve the engine's namespace.
         
         returns: actual result of f(*args, **kwargs)
         """
         d = self._defaults('block', 'bound')
-        return self._apply(f,args,kwargs, block=True, bound=False, **d)
+        return self.client.apply(f,args,kwargs, block=True, bound=False, **d)
 
     @sync_results
     @save_ids
     def apply_bound(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) bound to engine namespace(s).
         
         if self.block is False:
             returns msg_id
         else:
             returns actual result of f(*args, **kwargs)
         
         This method has access to the targets' globals
         
         """
         d = self._defaults('bound')
-        return self._apply(f, args, kwargs, bound=True, **d)
+        return self.client.apply(f, args, kwargs, bound=True, **d)
 
     @sync_results
     @save_ids
     def apply_async_bound(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) bound to engine namespace(s) 
         in a nonblocking manner.
         
         returns: msg_id
         
         This method has access to the targets' globals
         
         """
         d = self._defaults('block', 'bound')
-        return self._apply(f, args, kwargs, block=False, bound=True, **d)
+        return self.client.apply(f, args, kwargs, block=False, bound=True, **d)
 
     @spin_after
     @save_ids
     def apply_sync_bound(self, f, *args, **kwargs):
         """calls f(*args, **kwargs) bound to engine namespace(s), waiting for the result.
         
         returns: actual result of f(*args, **kwargs)
         
         This method has access to the targets' globals
         
         """
         d = self._defaults('block', 'bound')
-        return self._apply(f, args, kwargs, block=True, bound=True, **d)
-    
-    @spin_after
-    @save_ids
-    def map(self, f, *sequences):
-        """Parallel version of builtin `map`, using this view's engines."""
-        if isinstance(self.targets, int):
-            targets = [self.targets]
-        else:
-            targets = self.targets
-        pf = ParallelFunction(self.client, f, block=self.block,
-                        bound=True, targets=targets)
-        return pf.map(*sequences)
-    
-    def parallel(self, bound=True, block=True):
-        """Decorator for making a ParallelFunction"""
-        return parallel(self.client, bound=bound, targets=self.targets, block=block)
+        return self.client.apply(f, args, kwargs, block=True, bound=True, **d)
     
     def abort(self, msg_ids=None, block=None):
         """Abort jobs on my engines.
         
         Parameters
         ----------
         
         msg_ids : None, str, list of strs, optional
             if None: abort all jobs.
             else: abort specific msg_id(s).
         """
         block = block if block is not None else self.block
         return self.client.abort(msg_ids=msg_ids, targets=self.targets, block=block)
 
     def queue_status(self, verbose=False):
         """Fetch the Queue status of my engines"""
         return self.client.queue_status(targets=self.targets, verbose=verbose)
     
     def purge_results(self, msg_ids=[], targets=[]):
         """Instruct the controller to forget specific results."""
         if targets is None or targets == 'all':
             targets = self.targets
         return self.client.purge_results(msg_ids=msg_ids, targets=targets)
+        
+    #-------------------------------------------------------------------
+    # Decorators
+    #-------------------------------------------------------------------
+    def parallel(self, bound=True, block=True):
+        """Decorator for making a ParallelFunction"""
+        return parallel(self.client, bound=bound, targets=self.targets, block=block, balanced=self._balanced)
+    
+    def remote(self, bound=True, block=True):
+        """Decorator for making a RemoteFunction"""
+        return parallel(self.client, bound=bound, targets=self.targets, block=block, balanced=self._balanced)
     
 
 
 class DirectView(View):
     """Direct Multiplexer View of one or more engines.
     
     These are created via indexed access to a client:
     
     >>> dv_1 = client[1]
     >>> dv_all = client[:]
     >>> dv_even = client[::2]
     >>> dv_some = client[1:3]
     
     This object provides dictionary access to engine namespaces:
     
     # push a=5:
     >>> dv['a'] = 5 
     # pull 'foo':
     >>> db['foo']
     
     """
     
+    def __init__(self, client=None, targets=None):
+        super(DirectView, self).__init__(client=client, targets=targets)
+        self._balanced = False
+    
+    @spin_after
+    @save_ids
+    def map(self, f, *sequences, **kwargs):
+        """Parallel version of builtin `map`, using this View's `targets`.
+        
+        There will be one task per target, so work will be chunked
+        if the sequences are longer than `targets`.  
+        
+        Results can be iterated as they are ready, but will become available in chunks.
+        
+        Parameters
+        ----------
+        
+        f : callable
+            function to be mapped
+        *sequences: one or more sequences of matching length
+            the sequences to be distributed and passed to `f`
+        block : bool
+            whether to wait for the result or not [default self.block]
+        bound : bool
+            whether to wait for the result or not [default self.bound]
+        
+        Returns
+        -------
+        
+        if block=False:
+            AsyncMapResult
+                An object like AsyncResult, but which reassembles the sequence of results
+                into a single list. AsyncMapResults can be iterated through before all
+                results are complete.
+            else:
+                the result of map(f,*sequences)
+        """
+        
+        block = kwargs.get('block', self.block)
+        bound = kwargs.get('bound', self.bound)
+        for k in kwargs.keys():
+            if k not in ['block', 'bound']:
+                raise TypeError("invalid keyword arg, %r"%k)
+        
+        assert len(sequences) > 0, "must have some sequences to map onto!"
+        pf = ParallelFunction(self.client, f, block=block,
+                        bound=bound, targets=self.targets, balanced=False)
+        return pf.map(*sequences)
+    
+    def map_async(self, f, *sequences, **kwargs):
+        """Parallel version of builtin `map`, using this view's engines."""
+        if 'block' in kwargs:
+            raise TypeError("map_async doesn't take a `block` keyword argument.")
+        kwargs['block'] = True
+        return self.map(f,*sequences,**kwargs)
+    
     @sync_results
     @save_ids
     def execute(self, code, block=True):
         """execute some code on my targets."""
         return self.client.execute(code, block=block, targets=self.targets)
     
     def update(self, ns):
         """update remote namespace with dict `ns`"""
         return self.client.push(ns, targets=self.targets, block=self.block)
     
     push = update
     
     def get(self, key_s):
         """get object(s) by `key_s` from remote namespace
         will return one object if it is a key.
         It also takes a list of keys, and will return a list of objects."""
         # block = block if block is not None else self.block
         return self.client.pull(key_s, block=True, targets=self.targets)
     
     @sync_results
     @save_ids
     def pull(self, key_s, block=True):
         """get object(s) by `key_s` from remote namespace
         will return one object if it is a key.
         It also takes a list of keys, and will return a list of objects."""
         block = block if block is not None else self.block
         return self.client.pull(key_s, block=block, targets=self.targets)
     
     def scatter(self, key, seq, dist='b', flatten=False, targets=None, block=None):
         """
         Partition a Python sequence and send the partitions to a set of engines.
         """
         block = block if block is not None else self.block
         targets = targets if targets is not None else self.targets
         
         return self.client.scatter(key, seq, dist=dist, flatten=flatten,
                     targets=targets, block=block)
     
     @sync_results
     @save_ids
     def gather(self, key, dist='b', targets=None, block=None):
         """
         Gather a partitioned sequence on a set of engines as a single local seq.
         """
         block = block if block is not None else self.block
         targets = targets if targets is not None else self.targets
         
         return self.client.gather(key, dist=dist, targets=targets, block=block)
     
     def __getitem__(self, key):
         return self.get(key)
     
     def __setitem__(self,key, value):
         self.update({key:value})
     
     def clear(self, block=False):
         """Clear the remote namespaces on my engines."""
         block = block if block is not None else self.block
         return self.client.clear(targets=self.targets, block=block)
     
     def kill(self, block=True):
         """Kill my engines."""
         block = block if block is not None else self.block
         return self.client.kill(targets=self.targets, block=block)
     
     #----------------------------------------
     # activate for %px,%autopx magics
     #----------------------------------------
     def activate(self):
         """Make this `View` active for parallel magic commands.
         
         IPython has a magic command syntax to work with `MultiEngineClient` objects.
         In a given IPython session there is a single active one.  While
         there can be many `Views` created and used by the user, 
         there is only one active one.  The active `View` is used whenever 
         the magic commands %px and %autopx are used.
         
         The activate() method is called on a given `View` to make it 
         active.  Once this has been done, the magic commands can be used.
         """
         
         try:
             # This is injected into __builtins__.
             ip = get_ipython()
         except NameError:
             print "The IPython parallel magics (%result, %px, %autopx) only work within IPython."
         else:
             pmagic = ip.plugin_manager.get_plugin('parallelmagic')
             if pmagic is not None:
                 pmagic.active_multiengine_client = self
             else:
                 print "You must first load the parallelmagic extension " \
                       "by doing '%load_ext parallelmagic'"
 
     
 class LoadBalancedView(View):
-    """An engine-agnostic View that only executes via the Task queue.
+    """An load-balancing View that only executes via the Task scheduler.
     
-    Typically created via:
+    Load-balanced views can be created with the client's `view` method:
     
-    >>> v = client[None]
-    <LoadBalancedView None>
+    >>> v = client.view(balanced=True)
     
-    but can also be created with:
+    or targets can be specified, to restrict the potential destinations:
     
     >>> v = client.view([1,3],balanced=True)
     
     which would restrict loadbalancing to between engines 1 and 3.
     
     """
     
     _apply_name = 'apply_balanced'
-    _default_names = ['targets', 'block', 'bound', 'follow', 'after', 'timeout']
+    _default_names = ['block', 'bound', 'follow', 'after', 'timeout']
     
-    def __init__(self, client, targets=None):
-        super(LoadBalancedView, self).__init__(client, targets)
+    def __init__(self, client=None, targets=None):
+        super(LoadBalancedView, self).__init__(client=client, targets=targets)
         self._ntargets = 1
-        self._apply_name = 'apply_balanced'
+    
+    def _validate_dependency(self, dep):
+        """validate a dependency.
+        
+        For use in `set_flags`.
+        """
+        if dep is None or isinstance(dep, (str, AsyncResult, Dependency)):
+            return True
+        elif isinstance(dep, (list,set, tuple)):
+            for d in dep:
+                if not isinstance(d, str, AsyncResult):
+                    return False
+        elif isinstance(dep, dict):
+            if set(dep.keys()) != set(Dependency().as_dict().keys()):
+                return False
+            if not isinstance(dep['msg_ids'], list):
+                return False
+            for d in dep['msg_ids']:
+                if not isinstance(d, str):
+                    return False
+        else:
+            return False
+                
+    def set_flags(self, **kwargs):
+        """set my attribute flags by keyword.
+        
+        A View is a wrapper for the Client's apply method, but
+        with attributes that specify keyword arguments, those attributes
+        can be set by keyword argument with this method.
+        
+        Parameters
+        ----------
+        
+        block : bool
+            whether to wait for results
+        bound : bool
+            whether to use the engine's namespace
+        follow : Dependency, list, msg_id, AsyncResult
+            the location dependencies of tasks
+        after : Dependency, list, msg_id, AsyncResult
+            the time dependencies of tasks
+        timeout : int,None
+            the timeout to be used for tasks
+        """
+        
+        super(LoadBalancedView, self).set_flags(**kwargs)
+        for name in ('follow', 'after'):
+            if name in kwargs:
+                value = kwargs[name]
+                if self._validate_dependency(value):
+                    setattr(self, name, value)
+                else:
+                    raise ValueError("Invalid dependency: %r"%value)
+        if 'timeout' in kwargs:
+            t = kwargs['timeout']
+            if not isinstance(t, (int, long, float, None)):
+                raise TypeError("Invalid type for timeout: %r"%type(t))
+            if t is not None:
+                if t < 0:
+                    raise ValueError("Invalid timeout: %s"%t)
+            self.timeout = t
+                
+    @spin_after
+    @save_ids
+    def map(self, f, *sequences, **kwargs):
+        """Parallel version of builtin `map`, load-balanced by this View.
+        
+        Each element will be a separate task, and will be load-balanced.  This
+        lets individual elements be available for iteration as soon as they arrive.
+        
+        Parameters
+        ----------
+        
+        f : callable
+            function to be mapped
+        *sequences: one or more sequences of matching length
+            the sequences to be distributed and passed to `f`
+        block : bool
+            whether to wait for the result or not [default self.block]
+        bound : bool
+            whether to use the engine's namespace
+        
+        Returns
+        -------
+        
+        if block=False:
+            AsyncMapResult
+                An object like AsyncResult, but which reassembles the sequence of results
+                into a single list. AsyncMapResults can be iterated through before all
+                results are complete.
+            else:
+                the result of map(f,*sequences)
+        
+        """
+        
+        block = kwargs.get('block', self.block)
+        bound = kwargs.get('bound', self.bound)
+        
+        assert len(sequences) > 0, "must have some sequences to map onto!"
+        
+        pf = ParallelFunction(self.client, f, block=block, bound=bound, 
+                                targets=self.targets, balanced=True)
+        return pf.map(*sequences)
+    
+    def map_async(self, f, *sequences, **kwargs):
+        """Parallel version of builtin `map`, using this view's engines.
+        
+        This is equivalent to map(...block=False)
+        
+        See `map` for details.
+        """
+        
+        if 'block' in kwargs:
+            raise TypeError("map_async doesn't take a `block` keyword argument.")
+        kwargs['block'] = True
+        return self.map(f,*sequences,**kwargs)
+    
     

docs/source/parallelz/parallel_multiengine.txt

@@ -1,818 +1,796 b''
 .. _parallelmultiengine:
 
 ==========================
 IPython's Direct interface
 ==========================
 
 The direct, or multiengine, interface represents one possible way of working with a set of
 IPython engines. The basic idea behind the multiengine interface is that the
 capabilities of each engine are directly and explicitly exposed to the user.
 Thus, in the multiengine interface, each engine is given an id that is used to
 identify the engine and give it work to do. This interface is very intuitive
 and is designed with interactive usage in mind, and is thus the best place for
 new users of IPython to begin.
 
 Starting the IPython controller and engines
 ===========================================
 
 To follow along with this tutorial, you will need to start the IPython
 controller and four IPython engines. The simplest way of doing this is to use
 the :command:`ipclusterz` command::
 
     $ ipclusterz start -n 4
     
 For more detailed information about starting the controller and engines, see
 our :ref:`introduction <ip1par>` to using IPython for parallel computing.
 
 Creating a ``Client`` instance
 ==============================
 
 The first step is to import the IPython :mod:`IPython.zmq.parallel.client`
 module and then create a :class:`.Client` instance:
 
 .. sourcecode:: ipython
 
     In [1]: from IPython.zmq.parallel import client
     
     In [2]: rc = client.Client()
 
 This form assumes that the default connection information (stored in
-:file:`ipcontroller-client.json` found in `~/.ipython/clusterz_default/security`) is
+:file:`ipcontroller-client.json` found in :file:`IPYTHON_DIR/clusterz_default/security`) is
 accurate. If the controller was started on a remote machine, you must copy that connection
 file to the client machine, or enter its contents as arguments to the Client constructor:
 
 .. sourcecode:: ipython
 
     # If you have copied the json connector file from the controller:
     In [2]: rc = client.Client('/path/to/ipcontroller-client.json')
-    # for a remote controller at 10.0.1.5, visible from my.server.com:
+    # or for a remote controller at 10.0.1.5, visible from my.server.com:
     In [3]: rc = client.Client('tcp://10.0.1.5:12345', sshserver='my.server.com')
     
 
-To make sure there are engines connected to the controller, use can get a list
+To make sure there are engines connected to the controller, users can get a list
 of engine ids:
 
 .. sourcecode:: ipython
 
     In [3]: rc.ids
-    Out[3]: set([0, 1, 2, 3])
+    Out[3]: [0, 1, 2, 3]
 
 Here we see that there are four engines ready to do work for us.
 
 Quick and easy parallelism
 ==========================
 
 In many cases, you simply want to apply a Python function to a sequence of
 objects, but *in parallel*. The client interface provides a simple way
 of accomplishing this: using the builtin :func:`map` and the ``@remote``
 function decorator, or the client's :meth:`map` method.
 
 Parallel map
 ------------
 
 Python's builtin :func:`map` functions allows a function to be applied to a
 sequence element-by-element. This type of code is typically trivial to
 parallelize. In fact, since IPython's interface is all about functions anyway,
-you can just use the builtin :func:`map`, or a client's :meth:`map` method:
+you can just use the builtin :func:`map` with a :class:`RemoteFunction`, or a 
+DirectView's :meth:`map` method:
 
 .. sourcecode:: ipython
 
     In [62]: serial_result = map(lambda x:x**10, range(32))
 
-    In [66]: parallel_result = rc.map(lambda x: x**10, range(32))
+    In [66]: parallel_result = rc[:].map(lambda x: x**10, range(32))
 
-    In [67]: serial_result==parallel_result
+    In [67]: serial_result==parallel_result.get()
     Out[67]: True
 
 
 .. note::
 
-    The client's own version of :meth:`map` or that of :class:`.DirectView` do
+    The :class:`DirectView`'s version of :meth:`map` does
     not do any load balancing. For a load balanced version, use a
     :class:`LoadBalancedView`, or a :class:`ParallelFunction` with
-    `targets=None`.
+    `balanced=True`.
 
 .. seealso::
     
     :meth:`map` is implemented via :class:`.ParallelFunction`.
 
 Remote function decorator
 -------------------------
 
 Remote functions are just like normal functions, but when they are called,
 they execute on one or more engines, rather than locally. IPython provides
 some decorators:
 
 .. sourcecode:: ipython
 
-    In [10]: @rc.remote(block=True)
+    In [10]: @rc.remote(block=True, targets=0)
        ....: def f(x):
        ....:     return 10.0*x**4
        ....: 
 
-    In [11]: map(f, range(32))    # this is done in parallel
+    In [11]: map(f, range(32))    # this is done on engine 0
     Out[11]: [0.0,10.0,160.0,...]
 
-See the docstring for the :func:`parallel` and :func:`remote` decorators for
-options.
+.. seealso::
+
+    See the docstring for the :func:`parallel` and :func:`remote` decorators for
+    options.
 
 Calling Python functions
 ========================
 
 The most basic type of operation that can be performed on the engines is to
 execute Python code or call Python functions. Executing Python code can be
 done in blocking or non-blocking mode (non-blocking is default) using the
 :meth:`execute` method, and calling functions can be done via the
 :meth:`.View.apply` method.
 
 apply
 -----
 
 The main method for doing remote execution (in fact, all methods that
 communicate with the engines are built on top of it), is :meth:`Client.apply`.
 Ideally, :meth:`apply` would have the signature ``apply(f,*args,**kwargs)``,
 which would call ``f(*args,**kwargs)`` remotely.  However, since :class:`Clients`
 require some more options, they cannot easily provide this interface.
 Instead, they provide the signature::
 
     c.apply(f, args=None, kwargs=None, bound=True, block=None, targets=None,
                     after=None, follow=None, timeout=None)
 
 In order to provide the nicer interface, we have :class:`View` classes, which wrap
 :meth:`Client.apply` by using attributes and extra :meth:`apply_x` methods to determine
 the extra arguments. For instance, performing index-access on a client creates a
-:class:`.LoadBalancedView`.
+:class:`.DirectView`.
 
 .. sourcecode:: ipython
 
     In [4]: view = rc[1:3]
     Out[4]: <DirectView [1, 2]>
 
     In [5]: view.apply<tab>
     view.apply  view.apply_async  view.apply_async_bound  view.apply_bound  view.apply_sync  view.apply_sync_bound
 
 A :class:`DirectView` always uses its `targets` attribute, and it will use its `bound`
 and `block` attributes in its :meth:`apply` method, but the suffixed :meth:`apply_x`
 methods allow specifying `bound` and `block` via the different methods.
 
 ==================  ==========  ==========
 method              block       bound
 ==================  ==========  ==========
 apply               self.block  self.bound
 apply_sync          True        False
 apply_async         False       False
 apply_sync_bound    True        True
 apply_async_bound   False       True
 ==================  ==========  ==========
 
 For explanation of these values, read on.
 
 Blocking execution
 ------------------
 
 In blocking mode, the :class:`.DirectView` object (called ``dview`` in
 these examples) submits the command to the controller, which places the
 command in the engines' queues for execution. The :meth:`apply` call then
 blocks until the engines are done executing the command:
 
 .. sourcecode:: ipython
 
     In [2]: rc.block=True
     In [3]: dview = rc[:] # A DirectView of all engines
     In [4]: dview['a'] = 5
 
     In [5]: dview['b'] = 10
 
     In [6]: dview.apply_bound(lambda x: a+b+x, 27)
     Out[6]: [42, 42, 42, 42]
 
 Python commands can be executed on specific engines by calling execute using
 the ``targets`` keyword argument, or creating a :class:`DirectView` instance
 by index-access to the client:
 
 .. sourcecode:: ipython
 
     In [6]: rc[::2].execute('c=a+b') # shorthand for rc.execute('c=a+b',targets=[0,2])
 
     In [7]: rc[1::2].execute('c=a-b') # shorthand for rc.execute('c=a-b',targets=[1,3])
 
     In [8]: rc[:]['c'] # shorthand for rc.pull('c',targets='all')
     Out[8]: [15, -5, 15, -5]
 
 .. note::
 
     Note that every call to ``rc.<meth>(...,targets=x)`` can be made via
     ``rc[<x>].<meth>(...)``, which constructs a View object. The only place
     where this differs in in :meth:`apply`. The :class:`Client` takes many
     arguments to apply, so it requires `args` and `kwargs` to be passed as
     individual arguments. Extended options such as `bound`,`targets`, and
     `block` are controlled by the attributes of the :class:`View` objects, so
     they can provide the much more convenient
     :meth:`View.apply(f,*args,**kwargs)`, which simply calls
     ``f(*args,**kwargs)`` remotely.
 
 This example also shows one of the most important things about the IPython
 engines: they have a persistent user namespaces. The :meth:`apply` method can
 be run in either a bound or unbound way. The default for a View is to be
 unbound, unless called by the :meth:`apply_bound` method:
 
 .. sourcecode:: ipython
 
-    In [9]: rc[:]['b'] = 5 # assign b to 5 everywhere
+    In [9]: dview['b'] = 5 # assign b to 5 everywhere
     
     In [10]: v0 = rc[0]
     
     In [12]: v0.apply_bound(lambda : b)
     Out[12]: 5
     
     In [13]: v0.apply(lambda : b)
     ---------------------------------------------------------------------------
     RemoteError                               Traceback (most recent call last)
     /home/you/<ipython-input-34-21a468eb10f0> in <module>()
     ----> 1 v0.apply(lambda : b)
     ...
     RemoteError: NameError(global name 'b' is not defined)
     Traceback (most recent call last):
       File "/Users/minrk/dev/ip/mine/IPython/zmq/parallel/streamkernel.py", line 294, in apply_request
         exec code in working, working
       File "<string>", line 1, in <module>
       File "<ipython-input-34-21a468eb10f0>", line 1, in <lambda>
     NameError: global name 'b' is not defined
     
 
 Specifically, `bound=True` specifies that the engine's namespace is to be used
 for execution, and `bound=False` specifies that the engine's namespace is not
 to be used (hence, 'b' is undefined during unbound execution, since the
 function is called in an empty namespace). Unbound execution is often useful
 for large numbers of atomic tasks, which prevents bloating the engine's
 memory, while bound execution lets you build on your previous work.
 
 
 Non-blocking execution
 ----------------------
 
 In non-blocking mode, :meth:`apply` submits the command to be executed and
 then returns a :class:`AsyncResult` object immediately. The
 :class:`AsyncResult` object gives you a way of getting a result at a later
 time through its :meth:`get` method. 
 
 .. Note::
 
     The :class:`AsyncResult` object provides a superset of the interface in 
     :py:class:`multiprocessing.pool.AsyncResult`.  See the 
     `official Python documentation <http://docs.python.org/library/multiprocessing#multiprocessing.pool.AsyncResult>`_
     for more.
 
 
 This allows you to quickly submit long running commands without blocking your
 local Python/IPython session:
 
 .. sourcecode:: ipython
     
     # define our function
     In [6]: def wait(t):
        ...:     import time
        ...:     tic = time.time()
        ...:     time.sleep(t)
        ...:     return time.time()-tic
     
     # In non-blocking mode
-    In [7]: pr = rc[:].apply_async(wait, 2)
+    In [7]: pr = dview.apply_async(wait, 2)
 
     # Now block for the result
     In [8]: pr.get()
     Out[8]: [2.0006198883056641, 1.9997570514678955, 1.9996809959411621, 2.0003249645233154]
 
     # Again in non-blocking mode
-    In [9]: pr = rc[:].apply_async(wait, 10)
+    In [9]: pr = dview.apply_async(wait, 10)
 
     # Poll to see if the result is ready
     In [10]: pr.ready()
     Out[10]: False
     
     # ask for the result, but wait a maximum of 1 second:
     In [45]: pr.get(1)
     ---------------------------------------------------------------------------
     TimeoutError                              Traceback (most recent call last)
     /home/you/<ipython-input-45-7cd858bbb8e0> in <module>()
     ----> 1 pr.get(1)
 
     /path/to/site-packages/IPython/zmq/parallel/asyncresult.pyc in get(self, timeout)
          62                 raise self._exception
          63         else:
     ---> 64             raise error.TimeoutError("Result not ready.")
          65 
          66     def ready(self):
 
     TimeoutError: Result not ready.
 
 .. Note::
 
     Note the import inside the function. This is a common model, to ensure
     that the appropriate modules are imported where the task is run.
 
 Often, it is desirable to wait until a set of :class:`AsyncResult` objects
 are done. For this, there is a the method :meth:`barrier`. This method takes a
 tuple of :class:`AsyncResult` objects (or `msg_ids`) and blocks until all of the 
 associated results are ready:
 
 .. sourcecode:: ipython
 
     In [72]: rc.block=False
 
     # A trivial list of AsyncResults objects
-    In [73]: pr_list = [rc[:].apply_async(wait, 3) for i in range(10)]
+    In [73]: pr_list = [dview.apply_async(wait, 3) for i in range(10)]
 
     # Wait until all of them are done
     In [74]: rc.barrier(pr_list)
 
     # Then, their results are ready using get() or the `.r` attribute
     In [75]: pr_list[0].get()
     Out[75]: [2.9982571601867676, 2.9982588291168213, 2.9987530708312988, 2.9990990161895752]
     
 
 
-The ``block`` and ``targets`` keyword arguments and attributes
---------------------------------------------------------------
-
-.. warning::
-
-    This is different now, I haven't updated this section.
-    -MinRK
+The ``block`` keyword argument and attributes
+---------------------------------------------
 
 Most methods(like :meth:`apply`) accept
-``block`` and ``targets`` as keyword arguments. As we have seen above, these
-keyword arguments control the blocking mode and which engines the command is
-applied to. The :class:`Client` class also has :attr:`block` and
-:attr:`targets` attributes that control the default behavior when the keyword
-arguments are not provided. Thus the following logic is used for :attr:`block`
-and :attr:`targets`:
+``block`` as a keyword argument. As we have seen above, these
+keyword arguments control the blocking mode . The :class:`Client` class also has 
+a :attr:`block` attribute that controls the default behavior when the keyword
+argument is not provided. Thus the following logic is used for :attr:`block`:
 
 * If no keyword argument is provided, the instance attributes are used.
-* Keyword argument, if provided override the instance attributes.
+* Keyword argument, if provided override the instance attributes for
+  the duration of a single call.
 
 The following examples demonstrate how to use the instance attributes:
 
 .. sourcecode:: ipython
 
-    In [16]: rc.targets = [0,2]
-
     In [17]: rc.block = False
 
-    In [18]: pr = rc.execute('a=5')
-
-    In [19]: pr.r
-    Out[19]: 
-    <Results List>
-    [0] In [6]: a=5
-    [2] In [6]: a=5
+    In [18]: ar = rc.apply(lambda : 10, targets=[0,2])
 
-    # Note targets='all' means all engines
-    In [20]: rc.targets = 'all'
+    In [19]: ar.get()
+    Out[19]: [10,10]
 
     In [21]: rc.block = True
 
-    In [22]: rc.execute('b=10; print b')
-    Out[22]: 
-    <Results List>
-    [0] In [7]: b=10; print b
-    [0] Out[7]: 10
-
-    [1] In [6]: b=10; print b
-    [1] Out[6]: 10
-
-    [2] In [7]: b=10; print b
-    [2] Out[7]: 10
-
-    [3] In [6]: b=10; print b
-    [3] Out[6]: 10
+    # Note targets='all' means all engines
+    In [22]: rc.apply(lambda : 42, targets='all')
+    Out[22]: [42, 42, 42, 42]
 
-The :attr:`block` and :attr:`targets` instance attributes also determine the
-behavior of the parallel magic commands.
+The :attr:`block` and :attr:`targets` instance attributes of the
+:class:`.DirectView` also determine the behavior of the parallel magic commands.
 
 
 Parallel magic commands
 -----------------------
 
 .. warning::
 
     The magics have not been changed to work with the zeromq system. ``%px``
     and ``%autopx`` do work, but ``%result`` does not. %px and %autopx *do
     not* print stdin/out.
 
 We provide a few IPython magic commands (``%px``, ``%autopx`` and ``%result``)
 that make it more pleasant to execute Python commands on the engines
 interactively. These are simply shortcuts to :meth:`execute` and
 :meth:`get_result`. The ``%px`` magic executes a single Python command on the
 engines specified by the :attr:`targets` attribute of the
 :class:`MultiEngineClient` instance (by default this is ``'all'``):
 
 .. sourcecode:: ipython
 
     # Create a DirectView for all targets
     In [22]: dv = rc[:]
     
     # Make this DirectView active for parallel magic commands
     In [23]: dv.activate()
 
     In [24]: dv.block=True
 
     In [25]: import numpy
 
     In [26]: %px import numpy
     Parallel execution on engines: [0, 1, 2, 3]
     Out[26]:[None,None,None,None]
 
     In [27]: %px a = numpy.random.rand(2,2)
     Parallel execution on engines: [0, 1, 2, 3]
 
     In [28]: %px ev = numpy.linalg.eigvals(a)
     Parallel execution on engines: [0, 1, 2, 3]
 
     In [28]: dv['ev']
     Out[44]: [ array([ 1.09522024, -0.09645227]), 
                array([ 1.21435496, -0.35546712]), 
                array([ 0.72180653,  0.07133042]), 
                array([  1.46384341e+00,   1.04353244e-04])
              ]
 
 .. Note::
 
     ``%result`` doesn't work
 
 The ``%result`` magic gets and prints the stdin/stdout/stderr of the last
 command executed on each engine. It is simply a shortcut to the
 :meth:`get_result` method:
 
 .. sourcecode:: ipython
 
     In [29]: %result
     Out[29]:
     <Results List>
     [0] In [10]: print numpy.linalg.eigvals(a)
     [0] Out[10]: [ 1.28167017  0.14197338]
 
     [1] In [9]: print numpy.linalg.eigvals(a)
     [1] Out[9]: [-0.14093616  1.27877273]
 
     [2] In [10]: print numpy.linalg.eigvals(a)
     [2] Out[10]: [-0.37023573  1.06779409]
 
     [3] In [9]: print numpy.linalg.eigvals(a)
     [3] Out[9]: [ 0.83664764 -0.25602658]
 
 The ``%autopx`` magic switches to a mode where everything you type is executed
 on the engines given by the :attr:`targets` attribute:
 
 .. sourcecode:: ipython
 
     In [30]: dv.block=False
 
     In [31]: %autopx
     Auto Parallel Enabled
     Type %autopx to disable
 
     In [32]: max_evals = []
     <IPython.zmq.parallel.asyncresult.AsyncResult object at 0x17b8a70>
 
     In [33]: for i in range(100):
        ....:     a = numpy.random.rand(10,10)
        ....:     a = a+a.transpose()
        ....:     evals = numpy.linalg.eigvals(a)
        ....:     max_evals.append(evals[0].real)
        ....:
        ....:
     <IPython.zmq.parallel.asyncresult.AsyncResult object at 0x17af8f0>
 
     In [34]: %autopx
     Auto Parallel Disabled
 
     In [35]: dv.block=True
 
     In [36]: px ans= "Average max eigenvalue is: %f"%(sum(max_evals)/len(max_evals))
     Parallel execution on engines: [0, 1, 2, 3]
     
     In [37]: dv['ans']
     Out[37]: [ 'Average max eigenvalue is:  10.1387247332',
                'Average max eigenvalue is:  10.2076902286',
                'Average max eigenvalue is:  10.1891484655',
                'Average max eigenvalue is:  10.1158837784',]
 
 
 .. Note::
 
     Multiline ``%autpx`` gets fouled up by NameErrors, because IPython
     currently introspects too much.
 
 
 Moving Python objects around
 ============================
 
 In addition to calling functions and executing code on engines, you can
 transfer Python objects to and from your IPython session and the engines. In
 IPython, these operations are called :meth:`push` (sending an object to the
 engines) and :meth:`pull` (getting an object from the engines). 
 
 Basic push and pull
 -------------------
 
 Here are some examples of how you use :meth:`push` and :meth:`pull`:
 
 .. sourcecode:: ipython
 
     In [38]: rc.push(dict(a=1.03234,b=3453))
     Out[38]: [None,None,None,None]
 
     In [39]: rc.pull('a')
     Out[39]: [ 1.03234, 1.03234, 1.03234, 1.03234]
 
     In [40]: rc.pull('b',targets=0)
     Out[40]: 3453
 
     In [41]: rc.pull(('a','b'))
     Out[41]: [ [1.03234, 3453], [1.03234, 3453], [1.03234, 3453], [1.03234, 3453] ]
     
     # zmq client does not have zip_pull
     In [42]: rc.zip_pull(('a','b'))
     Out[42]: [(1.03234, 1.03234, 1.03234, 1.03234), (3453, 3453, 3453, 3453)]
 
     In [43]: rc.push(dict(c='speed'))
     Out[43]: [None,None,None,None]
 
 In non-blocking mode :meth:`push` and :meth:`pull` also return
 :class:`AsyncResult` objects:
 
 .. sourcecode:: ipython
 
     In [47]: rc.block=False
 
     In [48]: pr = rc.pull('a')
 
     In [49]: pr.get()
     Out[49]: [1.03234, 1.03234, 1.03234, 1.03234]
 
 
 
 
 Dictionary interface
 --------------------
 
 Since a namespace is just a :class:`dict`, :class:`DirectView` objects provide
 dictionary-style access by key and methods such as :meth:`get` and
 :meth:`update` for convenience. This make the remote namespaces of the engines
 appear as a local dictionary. Underneath, this uses :meth:`push` and
 :meth:`pull`:
 
 .. sourcecode:: ipython
 
     In [50]: rc.block=True
 
-    In [51]: rc[:]['a']=['foo','bar']
+    In [51]: dview['a']=['foo','bar']
 
-    In [52]: rc[:]['a']
+    In [52]: dview['a']
     Out[52]: [ ['foo', 'bar'], ['foo', 'bar'], ['foo', 'bar'], ['foo', 'bar'] ]
 
 Scatter and gather
 ------------------
 
 Sometimes it is useful to partition a sequence and push the partitions to
 different engines. In MPI language, this is know as scatter/gather and we
 follow that terminology. However, it is important to remember that in
 IPython's :class:`Client` class, :meth:`scatter` is from the
 interactive IPython session to the engines and :meth:`gather` is from the
 engines back to the interactive IPython session. For scatter/gather operations
 between engines, MPI should be used:
 
 .. sourcecode:: ipython
 
-    In [58]: rc.scatter('a',range(16))
+    In [58]: dview.scatter('a',range(16))
     Out[58]: [None,None,None,None]
 
-    In [59]: rc[:]['a']
+    In [59]: dview['a']
     Out[59]: [ [0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11], [12, 13, 14, 15] ]
 
-    In [60]: rc.gather('a')
+    In [60]: dview.gather('a')
     Out[60]: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
 
 Other things to look at
 =======================
 
 How to do parallel list comprehensions
 --------------------------------------
 
 In many cases list comprehensions are nicer than using the map function. While
 we don't have fully parallel list comprehensions, it is simple to get the
 basic effect using :meth:`scatter` and :meth:`gather`:
 
 .. sourcecode:: ipython
 
-    In [66]: rc.scatter('x',range(64))
+    In [66]: dview.scatter('x',range(64))
     Out[66]: [None,None,None,None]
 
     In [67]: px y = [i**10 for i in x]
     Parallel execution on engines: [0, 1, 2, 3]
     Out[67]: 
 
-    In [68]: y = rc.gather('y')
+    In [68]: y = dview.gather('y')
 
     In [69]: print y
     [0, 1, 1024, 59049, 1048576, 9765625, 60466176, 282475249, 1073741824,...]
 
 Parallel exceptions
 -------------------
 
 In the multiengine interface, parallel commands can raise Python exceptions,
 just like serial commands. But, it is a little subtle, because a single
 parallel command can actually raise multiple exceptions (one for each engine
 the command was run on). To express this idea, the MultiEngine interface has a
 :exc:`CompositeError` exception class that will be raised in most cases. The
 :exc:`CompositeError` class is a special type of exception that wraps one or
 more other types of exceptions. Here is how it works:
 
 .. sourcecode:: ipython
 
     In [76]: rc.block=True
 
     In [77]: rc.execute('1/0')
     ---------------------------------------------------------------------------
     CompositeError                            Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
     /ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in execute(self, lines, targets, block)
         432         targets, block = self._findTargetsAndBlock(targets, block)
         433         result = blockingCallFromThread(self.smultiengine.execute, lines,
     --> 434             targets=targets, block=block)
         435         if block:
         436             result = ResultList(result)
 
     /ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
          72             result.raiseException()
          73         except Exception, e:
     ---> 74             raise e
          75     return result
          76 
 
     CompositeError: one or more exceptions from call to method: execute
     [0:execute]: ZeroDivisionError: integer division or modulo by zero
     [1:execute]: ZeroDivisionError: integer division or modulo by zero
     [2:execute]: ZeroDivisionError: integer division or modulo by zero
     [3:execute]: ZeroDivisionError: integer division or modulo by zero
 
 Notice how the error message printed when :exc:`CompositeError` is raised has
 information about the individual exceptions that were raised on each engine.
 If you want, you can even raise one of these original exceptions:
 
 .. sourcecode:: ipython
 
     In [80]: try:
        ....:     rc.execute('1/0')
        ....: except client.CompositeError, e:
        ....:     e.raise_exception()
        ....:     
        ....:     
     ---------------------------------------------------------------------------
     ZeroDivisionError                         Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
     /ipython1-client-r3021/ipython1/kernel/error.pyc in raise_exception(self, excid)
         156             raise IndexError("an exception with index %i does not exist"%excid)
         157         else:
     --> 158             raise et, ev, etb
         159 
         160 def collect_exceptions(rlist, method):
 
     ZeroDivisionError: integer division or modulo by zero
 
 If you are working in IPython, you can simple type ``%debug`` after one of
 these :exc:`CompositeError` exceptions is raised, and inspect the exception
 instance:
 
 .. sourcecode:: ipython
 
     In [81]: rc.execute('1/0')
     ---------------------------------------------------------------------------
     CompositeError                            Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
     /ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in execute(self, lines, targets, block)
         432         targets, block = self._findTargetsAndBlock(targets, block)
         433         result = blockingCallFromThread(self.smultiengine.execute, lines,
     --> 434             targets=targets, block=block)
         435         if block:
         436             result = ResultList(result)
 
     /ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
          72             result.raiseException()
          73         except Exception, e:
     ---> 74             raise e
          75     return result
          76 
 
     CompositeError: one or more exceptions from call to method: execute
     [0:execute]: ZeroDivisionError: integer division or modulo by zero
     [1:execute]: ZeroDivisionError: integer division or modulo by zero
     [2:execute]: ZeroDivisionError: integer division or modulo by zero
     [3:execute]: ZeroDivisionError: integer division or modulo by zero
 
     In [82]: %debug
     > 
     
     /ipython1-client-r3021/ipython1/kernel/twistedutil.py(74)blockingCallFromThread()
          73         except Exception, e:
     ---> 74             raise e
          75     return result
 
     # With the debugger running, e is the exceptions instance.  We can tab complete
     # on it and see the extra methods that are available.
     ipdb> e.
     e.__class__         e.__getitem__       e.__new__           e.__setstate__      e.args
     e.__delattr__       e.__getslice__      e.__reduce__        e.__str__           e.elist
     e.__dict__          e.__hash__          e.__reduce_ex__     e.__weakref__       e.message
     e.__doc__           e.__init__          e.__repr__          e._get_engine_str   e.print_tracebacks
     e.__getattribute__  e.__module__        e.__setattr__       e._get_traceback    e.raise_exception
     ipdb> e.print_tracebacks()
     [0:execute]: 
     ---------------------------------------------------------------------------
     ZeroDivisionError                         Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<string> in <module>()
 
     ZeroDivisionError: integer division or modulo by zero
 
     [1:execute]: 
     ---------------------------------------------------------------------------
     ZeroDivisionError                         Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<string> in <module>()
 
     ZeroDivisionError: integer division or modulo by zero
 
     [2:execute]: 
     ---------------------------------------------------------------------------
     ZeroDivisionError                         Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<string> in <module>()
 
     ZeroDivisionError: integer division or modulo by zero
 
     [3:execute]: 
     ---------------------------------------------------------------------------
     ZeroDivisionError                         Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<string> in <module>()
 
     ZeroDivisionError: integer division or modulo by zero
 
 
 All of this same error handling magic even works in non-blocking mode:
 
 .. sourcecode:: ipython
 
     In [83]: rc.block=False
 
     In [84]: pr = rc.execute('1/0')
 
     In [85]: pr.get()
     ---------------------------------------------------------------------------
     CompositeError                            Traceback (most recent call last)
 
     /ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
     /ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in _get_r(self)
         170 
         171     def _get_r(self):
     --> 172         return self.get_result(block=True)
         173 
         174     r = property(_get_r)
 
     /ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in get_result(self, default, block)
         131                 return self.result
         132         try:
     --> 133             result = self.client.get_pending_deferred(self.result_id, block)
         134         except error.ResultNotCompleted:
         135             return default
 
     /ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in get_pending_deferred(self, deferredID, block)
         385 
         386     def get_pending_deferred(self, deferredID, block):
     --> 387         return blockingCallFromThread(self.smultiengine.get_pending_deferred, deferredID, block)
         388 
         389     def barrier(self, pendingResults):
 
     /ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
          72             result.raiseException()
          73         except Exception, e:
     ---> 74             raise e
          75     return result
          76 
 
     CompositeError: one or more exceptions from call to method: execute
     [0:execute]: ZeroDivisionError: integer division or modulo by zero
     [1:execute]: ZeroDivisionError: integer division or modulo by zero
     [2:execute]: ZeroDivisionError: integer division or modulo by zero
     [3:execute]: ZeroDivisionError: integer division or modulo by zero
 
 

docs/source/parallelz/parallel_task.txt

@@ -1,395 +1,395 b''
 .. _paralleltask:
 
 ==========================
 The IPython task interface
 ==========================
 
 The task interface to the cluster presents the engines as a fault tolerant,
 dynamic load-balanced system of workers. Unlike the multiengine interface, in
 the task interface the user have no direct access to individual engines. By
 allowing the IPython scheduler to assign work, this interface is simultaneously
 simpler and more powerful.
 
 Best of all, the user can use both of these interfaces running at the same time
 to take advantage of their respective strengths. When the user can break up
 the user's work into segments that do not depend on previous execution, the
 task interface is ideal. But it also has more power and flexibility, allowing
 the user to guide the distribution of jobs, without having to assign tasks to
 engines explicitly.
 
 Starting the IPython controller and engines
 ===========================================
 
 To follow along with this tutorial, you will need to start the IPython
 controller and four IPython engines. The simplest way of doing this is to use
 the :command:`ipclusterz` command::
 
 	$ ipclusterz start -n 4
 	
 For more detailed information about starting the controller and engines, see
 our :ref:`introduction <ip1par>` to using IPython for parallel computing.
 
 Creating a ``Client`` instance
 ==============================
 
 The first step is to import the IPython :mod:`IPython.zmq.parallel.client`
 module and then create a :class:`.Client` instance:
 
 .. sourcecode:: ipython
 
 	In [1]: from IPython.zmq.parallel import client
 	
 	In [2]: rc = client.Client()
 	
-	In [3]: lview = rc[None]
-	Out[3]: <LoadBalancedView tcp://127.0.0.1:10101>
+	In [3]: lview = rc.view(balanced=True)
+	Out[3]: <LoadBalancedView None>
     
 
 This form assumes that the controller was started on localhost with default
 configuration. If not, the location of the controller must be given as an
 argument to the constructor:
 
 .. sourcecode:: ipython
 
     # for a visible LAN controller listening on an external port:
     In [2]: rc = client.Client('tcp://192.168.1.16:10101')
     # for a remote controller at my.server.com listening on localhost:
     In [3]: rc = client.Client(sshserver='my.server.com')
 
 
 
 Quick and easy parallelism
 ==========================
 
 In many cases, you simply want to apply a Python function to a sequence of
 objects, but *in parallel*. Like the multiengine interface, these can be
 implemented via the task interface. The exact same tools can perform these
 actions in load-balanced ways as well as multiplexed ways: a parallel version
 of :func:`map` and :func:`@parallel` function decorator. If one specifies the
-argument `targets=None`, then they are dynamically load balanced. Thus, if the
+argument `balanced=True`, then they are dynamically load balanced. Thus, if the
 execution time per item varies significantly, you should use the versions in
 the task interface.
 
 Parallel map
 ------------
 
 To load-balance :meth:`map`,simply use a LoadBalancedView, created by asking
 for the ``None`` element:
 
 .. sourcecode:: ipython
 
 	In [63]: serial_result = map(lambda x:x**10, range(32))
 
-	In [64]: parallel_result = tc[None].map(lambda x:x**10, range(32))
+	In [64]: parallel_result = lview.map(lambda x:x**10, range(32), block=True)
 
 	In [65]: serial_result==parallel_result
 	Out[65]: True
 
 Parallel function decorator
 ---------------------------
 
 Parallel functions are just like normal function, but they can be called on
 sequences and *in parallel*. The multiengine interface provides a decorator
 that turns any Python function into a parallel function:
 
 .. sourcecode:: ipython
 
     In [10]: @lview.parallel()
        ....: def f(x):
        ....:     return 10.0*x**4
        ....:
 
     In [11]: f.map(range(32))    # this is done in parallel
     Out[11]: [0.0,10.0,160.0,...]
 
 Dependencies
 ============
 
 Often, pure atomic load-balancing is too primitive for your work. In these cases, you
 may want to associate some kind of `Dependency` that describes when, where, or whether
 a task can be run.  In IPython, we provide two types of dependencies: 
 `Functional Dependencies`_ and `Graph Dependencies`_
 
 .. note::
 
     It is important to note that the pure ZeroMQ scheduler does not support dependencies,
     and you will see errors or warnings if you try to use dependencies with the pure
     scheduler.
 
 Functional Dependencies
 -----------------------
 
 Functional dependencies are used to determine whether a given engine is capable of running
 a particular task.  This is implemented via a special :class:`Exception` class, 
 :class:`UnmetDependency`, found in `IPython.zmq.parallel.error`.  Its use is very simple: 
 if a task fails with an UnmetDependency exception, then the scheduler, instead of relaying
 the error up to the client like any other error, catches the error, and submits the task
 to a different engine.  This will repeat indefinitely, and a task will never be submitted
 to a given engine a second time.
 
 You can manually raise the :class:`UnmetDependency` yourself, but IPython has provided 
 some decorators for facilitating this behavior.
 
 There are two decorators and a class used for functional dependencies:
 
 .. sourcecode:: ipython
 
     In [9]: from IPython.zmq.parallel.dependency import depend, require, dependent
 
 @require
 ********
 
 The simplest sort of dependency is requiring that a Python module is available. The
 ``@require`` decorator lets you define a function that will only run on engines where names
 you specify are importable:
 
 .. sourcecode:: ipython
 
     In [10]: @require('numpy', 'zmq')
         ...: def myfunc():
         ...:     import numpy,zmq
         ...:     return dostuff()
 
 Now, any time you apply :func:`myfunc`, the task will only run on a machine that has
 numpy and pyzmq available.
 
 @depend
 *******
 
 The ``@depend`` decorator lets you decorate any function with any *other* function to
 evaluate the dependency. The dependency function will be called at the start of the task,
 and if it returns ``False``, then the dependency will be considered unmet, and the task
 will be assigned to another engine. If the dependency returns *anything other than
 ``False``*, the rest of the task will continue.
 
 .. sourcecode:: ipython
 
     In [10]: def platform_specific(plat):
         ...:    import sys
         ...:    return sys.platform == plat
     
     In [11]: @depend(platform_specific, 'darwin')
         ...: def mactask():
         ...:    do_mac_stuff()
 
     In [12]: @depend(platform_specific, 'nt')
         ...: def wintask():
         ...:    do_windows_stuff()
     
 In this case, any time you apply ``mytask``, it will only run on an OSX machine.
 ``@depend`` is just like ``apply``, in that it has a ``@depend(f,*args,**kwargs)``
 signature.
 
 dependents
 **********
 
 You don't have to use the decorators on your tasks, if for instance you may want
 to run tasks with a single function but varying dependencies, you can directly construct
 the :class:`dependent` object that the decorators use:
 
 .. sourcecode::ipython
 
     In [13]: def mytask(*args):
         ...:    dostuff()
     
     In [14]: mactask = dependent(mytask, platform_specific, 'darwin')
     # this is the same as decorating the declaration of mytask with @depend
     # but you can do it again:
     
     In [15]: wintask = dependent(mytask, platform_specific, 'nt')
     
     # in general:
     In [16]: t = dependent(f, g, *dargs, **dkwargs)
     
     # is equivalent to:
     In [17]: @depend(g, *dargs, **dkwargs)
         ...: def t(a,b,c):
         ...:     # contents of f
 
 Graph Dependencies
 ------------------
 
 Sometimes you want to restrict the time and/or location to run a given task as a function
 of the time and/or location of other tasks. This is implemented via a subclass of
 :class:`set`, called a :class:`Dependency`. A Dependency is just a set of `msg_ids`
 corresponding to tasks, and a few attributes to guide how to decide when the Dependency
 has been met.
 
 The switches we provide for interpreting whether a given dependency set has been met:
 
 any|all
     Whether the dependency is considered met if *any* of the dependencies are done, or
     only after *all* of them have finished.  This is set by a Dependency's :attr:`all`
     boolean attribute, which defaults to ``True``.
 
 success_only
     Whether to consider only tasks that did not raise an error as being fulfilled.
     Sometimes you want to run a task after another, but only if that task succeeded.  In
     this case, ``success_only`` should be ``True``.  However sometimes you may not care
     whether the task succeeds, and always want the second task to run, in which case
     you should use `success_only=False`.  The default behavior is to only use successes.
 
 There are other switches for interpretation that are made at the *task* level.  These are
 specified via keyword arguments to the client's :meth:`apply` method.
 
 after,follow
     You may want to run a task *after* a given set of dependencies have been run and/or
     run it *where* another set of dependencies are met. To support this, every task has an
     `after` dependency to restrict time, and a `follow` dependency to restrict
     destination.
 
 timeout
     You may also want to set a time-limit for how long the scheduler should wait before a
     task's dependencies are met. This is done via a `timeout`, which defaults to 0, which
     indicates that the task should never timeout. If the timeout is reached, and the
     scheduler still hasn't been able to assign the task to an engine, the task will fail
     with a :class:`DependencyTimeout`.
 
 .. note::
 
     Dependencies only work within the task scheduler. You cannot instruct a load-balanced
     task to run after a job submitted via the MUX interface.
 
 The simplest form of Dependencies is with `all=True,success_only=True`. In these cases,
 you can skip using Dependency objects, and just pass msg_ids or AsyncResult objects as the
 `follow` and `after` keywords to :meth:`client.apply`:
 
 .. sourcecode:: ipython
 
     In [14]: client.block=False
 
-    In [15]: ar = client.apply(f, args, kwargs, targets=None)
+    In [15]: ar = client.apply(f, args, kwargs, balanced=True)
 
-    In [16]: ar2 = client.apply(f2, targets=None)
+    In [16]: ar2 = client.apply(f2, balanced=True)
 
-    In [17]: ar3 = client.apply(f3, after=[ar,ar2])
+    In [17]: ar3 = client.apply(f3, after=[ar,ar2], balanced=True)
 
-    In [17]: ar4 = client.apply(f3, follow=[ar], timeout=2.5)
+    In [17]: ar4 = client.apply(f3, follow=[ar], timeout=2.5, balanced=True)
 
 
 .. seealso::
 
     Some parallel workloads can be described as a `Directed Acyclic Graph
     <http://en.wikipedia.org/wiki/Directed_acyclic_graph>`_, or DAG. See :ref:`DAG
     Dependencies <dag_dependencies>` for an example demonstrating how to use map a NetworkX DAG
     onto task dependencies.
 
 
 
 Impossible Dependencies
 ***********************
 
 The schedulers do perform some analysis on graph dependencies to determine whether they
 are not possible to be met. If the scheduler does discover that a dependency cannot be
 met, then the task will fail with an :class:`ImpossibleDependency` error. This way, if the
 scheduler realized that a task can never be run, it won't sit indefinitely in the
 scheduler clogging the pipeline.
 
 The basic cases that are checked:
 
 * depending on nonexistent messages
 * `follow` dependencies were run on more than one machine and `all=True`
 * any dependencies failed and `all=True,success_only=True`
 * all dependencies failed and `all=False,success_only=True`
 
 .. warning::
 
     This analysis has not been proven to be rigorous, so it is likely possible for tasks
     to become impossible to run in obscure situations, so a timeout may be a good choice.
 
 Schedulers
 ==========
 
 There are a variety of valid ways to determine where jobs should be assigned in a 
 load-balancing situation.  In IPython, we support several standard schemes, and
 even make it easy to define your own.  The scheme can be selected via the ``--scheme``
 argument to :command:`ipcontrollerz`, or in the :attr:`HubFactory.scheme` attribute
 of a controller config object.
 
 The built-in routing schemes:
 
 lru: Least Recently Used
 
     Always assign work to the least-recently-used engine.  A close relative of
     round-robin, it will be fair with respect to the number of tasks, agnostic 
     with respect to runtime of each task.
 
 plainrandom: Plain Random
     Randomly picks an engine on which to run.
 
 twobin: Two-Bin Random
 
     **Depends on numpy**
     
      Pick two engines at random, and use the LRU of the two. This is known to be better
     than plain random in many cases, but requires a small amount of computation.
 
 leastload: Least Load
 
     **This is the default scheme**
 
     Always assign tasks to the engine with the fewest outstanding tasks (LRU breaks tie).
 
 weighted: Weighted Two-Bin Random
 
     **Depends on numpy**
     
     Pick two engines at random using the number of outstanding tasks as inverse weights,
     and use the one with the lower load.
 
 
 Pure ZMQ Scheduler
 ------------------
 
 For maximum throughput, the 'pure' scheme is not Python at all, but a C-level
 :class:`MonitoredQueue` from PyZMQ, which uses a ZeroMQ ``XREQ`` socket to perform all
 load-balancing. This scheduler does not support any of the advanced features of the Python
 :class:`.Scheduler`.
 
 Disabled features when using the ZMQ Scheduler:
 
 * Engine unregistration
     Task farming will be disabled if an engine unregisters.  
     Further, if an engine is unregistered during computation, the scheduler may not recover.
 * Dependencies
     Since there is no Python logic inside the Scheduler, routing decisions cannot be made
     based on message content.
 * Early destination notification
     The Python schedulers know which engine gets which task, and notify the Hub.  This 
     allows graceful handling of Engines coming and going.  There is no way to know
     where ZeroMQ messages have gone, so there is no way to know what tasks are on which
     engine until they *finish*.  This makes recovery from engine shutdown very difficult.
   
 
 .. note::
 
     TODO: performance comparisons
 
 
 More details
 ============
 
 The :class:`Client` has many more powerful features that allow quite a bit
 of flexibility in how tasks are defined and run. The next places to look are
 in the following classes:
 
 * :class:`IPython.zmq.parallel.client.Client`
 * :class:`IPython.zmq.parallel.client.AsyncResult`
 * :meth:`IPython.zmq.parallel.client.Client.apply`
 * :mod:`IPython.zmq.parallel.dependency`
 
 The following is an overview of how to use these classes together:
 
 1. Create a :class:`Client`.
 2. Define some functions to be run as tasks
 3. Submit your tasks to using the :meth:`apply` method of your
-   :class:`Client` instance, specifying `targets=None`. This signals
+   :class:`Client` instance, specifying `balanced=True`. This signals
    the :class:`Client` to entrust the Scheduler with assigning tasks to engines.
 4. Use :meth:`Client.get_results` to get the results of the
    tasks, or use the :meth:`AsyncResult.get` method of the results to wait
    for and then receive the results.
 
 
 .. seealso::
 
     A demo of :ref:`DAG Dependencies <dag_dependencies>` with NetworkX and IPython.