Warning
This documentation is for an old version of IPython. You can find docs for newer versions here.
A semi-synchronous Client for the ZMQ cluster
Authors:
Bases: object
wrapper for finished Execute results
Bases: 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.
Bases: IPython.utils.traitlets.HasTraits
A semi-synchronous client to the IPython ZMQ cluster
Parameters: | url_file : str/unicode; path to ipcontroller-client.json
profile : bytes
cluster_id : str
context : zmq.Context
debug : bool
timeout : int/float
#————– session related args —————- : config : Config object
username : str
#————– 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
sshkey : str; path to ssh private key file
password : str
paramiko : bool
|
---|---|
Attributes: | ids : list of int engine IDs
history : list of msg_ids
outstanding : set of msg_ids
results : dict
block : bool
|
Methods: | spin :
wait :
execution methods :
data movement :
query methods :
control methods :
|
Abort specific jobs from the execution queues of target(s).
This is a mechanism to prevent jobs that have already been submitted from executing.
Parameters: | jobs : msg_id, list of msg_ids, or AsyncResult
|
---|
Create a DirectView and register it with IPython magics
Defines the magics %px, %autopx, %pxresult, %%px
Parameters: | targets: int, list of ints, or ‘all’ :
suffix: str [default: ‘’] :
|
---|
Clear the namespace in target(s).
Close my zmq Sockets
If linger, set the zmq LINGER socket option, which allows discarding of messages.
Query the Hub’s TaskRecord database
This will return a list of task record dicts that match query
Parameters: | query : mongodb query dict
keys : list of strs [optional]
|
---|
construct a DirectView object.
If no targets are specified, create a DirectView using all engines.
rc.direct_view(‘all’) is distinguished from rc[:] in that ‘all’ will evaluate the target engines at each execution, whereas rc[:] will connect to all current engines, and that list will not change.
That is, ‘all’ will always use all engines, whereas rc[:] will not use engines added after the DirectView is constructed.
Parameters: | targets: list,slice,int,etc. [default: use all engines] :
|
---|
Retrieve a result by msg_id or history index, wrapped in an AsyncResult object.
If the client already has the results, no request to the Hub will be made.
This is a convenient way to construct AsyncResult objects, which are wrappers that include metadata about execution, and allow for awaiting results that were not submitted by this Client.
It can also be a convenient way to retrieve the metadata associated with blocking execution, since it always retrieves
Parameters: | indices_or_msg_ids : integer history index, str msg_id, or list of either
block : bool
|
---|---|
Returns: | AsyncResult :
AsyncHubResult :
|
Examples
In [10]: r = client.apply()
Get the Hub’s history
Just like the Client, the Hub has a history, which is a list of msg_ids. This will contain the history of all clients, and, depending on configuration, may contain history across multiple cluster sessions.
Any msg_id returned here is a valid argument to get_result.
Returns: | msg_ids : list of strs
|
---|
Always up-to-date ids property.
construct a DirectView object.
If no arguments are specified, create a LoadBalancedView using all engines.
Parameters: | targets: list,slice,int,etc. [default: use all engines] :
|
---|
Clears all content from previous Tasks from both the hub and the local client
In addition to calling purge_results(“all”) it also deletes the history and other bookkeeping lists.
Tell the Hub to forget results.
Individual results can be purged by msg_id, or the entire history of specific targets can be purged.
Use purge_results(‘all’) to scrub everything from the Hub’s db.
Parameters: | jobs : str or list of str or AsyncResult objects
targets : int/str/list of ints/strs
|
---|
Clears the client caches of results and their metadata.
Individual results can be purged by msg_id, or the entire history of specific targets can be purged.
Use purge_local_results(‘all’) to scrub everything from the Clients’s results and metadata caches.
After this call all AsyncResults are invalid and should be discarded.
If you must “reget” the results, you can still do so by using client.get_result(msg_id) or client.get_result(asyncresult). This will redownload the results from the hub if they are still available (i.e client.purge_hub_results(...) has not been called.
Parameters: | jobs : str or list of str or AsyncResult objects
targets : int/list of ints
|
---|---|
Raises: | RuntimeError : if any of the tasks to be purged are still outstanding. |
Clears the cached results from both the hub and the local client
Individual results can be purged by msg_id, or the entire history of specific targets can be purged.
Use purge_results(‘all’) to scrub every cached result from both the Hub’s and the Client’s db.
Equivalent to calling both purge_hub_results() and purge_client_results() with the same arguments.
Parameters: | jobs : str or list of str or AsyncResult objects
targets : int/str/list of ints/strs
|
---|
Fetch the status of engine queues.
Parameters: | targets : int/str/list of ints/strs
verbose : bool
|
---|
Resubmit one or more tasks.
in-flight tasks may not be resubmitted.
Parameters: | indices_or_msg_ids : integer history index, str msg_id, or list of either
block : bool
|
---|---|
Returns: | AsyncHubResult :
|
Check on the status of the result(s) of the apply request with msg_ids.
If status_only is False, then the actual results will be retrieved, else only the status of the results will be checked.
Parameters: | msg_ids : list of msg_ids
status_only : bool (default: True)
|
---|---|
Returns: | results : dict
|
construct and send an apply message via a socket.
This is the principal method with which all engine execution is performed by views.
construct and send an execute request via a socket.
Terminates one or more engine processes, optionally including the hub.
Parameters: | targets: list of ints or ‘all’ [default: all] :
hub: bool [default: False] :
block: bool [default: self.block] :
restart: bool [default: False] :
|
---|
Flush any registration notifications and execution results waiting in the ZMQ queue.
call Client.spin() in a background thread on some regular interval
This helps ensure that messages don’t pile up too much in the zmq queue while you are working on other things, or just leaving an idle terminal.
It also helps limit potential padding of the received timestamp on AsyncResult objects, used for timings.
Parameters: | interval : float, optional
|
---|
Notes
For precision timing, you may want to use this method to put a bound on the jitter (in seconds) in received timestamps used in AsyncResult.wall_time.
stop background spin_thread, if any
waits on one or more jobs, for up to timeout seconds.
Parameters: | jobs : int, str, or list of ints and/or strs, or one or more AsyncResult objects
timeout : float
|
---|---|
Returns: | True : when all msg_ids are done False : timeout reached, some msg_ids still outstanding |