You should read through the quickstart before reading this document.

Distributed computing is hard for two reasons:

  1. Consistent coordination of distributed systems requires sophistication
  2. Concurrent network programming is tricky and error prone

The foundations of dask.distributed provide abstractions to hide some complexity of concurrent network programming (#2). These abstractions ease the construction of sophisticated parallel systems (#1) in a safer environment. However, as with all layered abstractions, ours has flaws. Critical feedback is welcome.

Concurrency with Tornado Coroutines

Worker and Scheduler nodes operate concurrently. They serve several overlapping requests and perform several overlapping computations at the same time without blocking. There are several approaches for concurrent programming, we’ve chosen to use Tornado for the following reasons:

  1. Developing and debugging is more comfortable without threads
  2. Tornado’s documentation is excellent
  3. Stackoverflow coverage is excellent
  4. Performance is satisfactory

Network Communication

Workers, the Scheduler, and Clients communicate with each other over the network. By default they use TCP connections as mediated by the abstract communications layer. The basic unit for dealing with established communications is the Comm object:

class distributed.comm.Comm[source]

A message-oriented communication object, representing an established communication channel. There should be only one reader and one writer at a time: to manage current communications, even with a single peer, you must create distinct Comm objects.

Messages are arbitrary Python objects. Concrete implementations of this class can implement different serialization mechanisms depending on the underlying transport’s characteristics.


Close the communication immediately and abruptly. Useful in destructors or generators’ finally blocks.


Close the communication cleanly. This will attempt to flush outgoing buffers before actually closing the underlying transport.

This method is a coroutine.


Return whether the stream is closed.


The peer’s address. For logging and debugging purposes only.


Read and return a message (a Python object). If deserialize is not None, it overrides this communication’s default setting.

This method is a coroutine.


Write a message (a Python object).

This method is a coroutine.

You don’t create Comm objects directly: you either listen for incoming communications, or connect to a peer listening for connections:

distributed.comm.connect(addr, timeout=3, deserialize=True)[source]

Connect to the given address (a URI such as tcp:// and yield a Comm object. If the connection attempt fails, it is retried until the timeout is expired.

distributed.comm.listen(addr, handle_comm, deserialize=True)[source]

Create a listener object with the given parameters. When its start() method is called, the listener will listen on the given address (a URI such as tcp:// and call handle_comm with a Comm object for each incoming connection.

handle_comm can be a regular function or a coroutine.

Listener objects expose the following interface:

class distributed.comm.core.Listener[source]

An address this listener can be contacted on. This can be different from listen_address if the latter is some wildcard address such as ‘tcp://‘.


The listening address as a URI string.


Start listening for incoming connections.


Stop listening. This does not shutdown already established communications, but prevents accepting new ones.


Communication addresses are canonically represented as URIs, such as tcp:// For compatibility with existing code, if the URI scheme is omitted, a default scheme of tcp is assumed (so is really the same as tcp:// The default scheme may change in the future.

The following schemes are currently implemented in the distributed source tree:

  • tcp is the main transport; it uses TCP sockets and allows for IPv4 and IPv6 addresses.
  • zmq is an experimental transport using ZeroMQ sockets; it is not recommended for production use.

Note that some URIs may be valid for listening but not for connecting. For example, the URI tcp:// will listen on all IPv4 and IPv6 addresses and on an arbitrary port, but you cannot connect to that address.

Higher-level APIs in distributed may accept other address formats for convenience or compatibility, for example a (host, port) pair. However, the abstract communications layer always deals with URIs.

Protocol Handling

While the abstract communication layer can transfer arbitrary Python objects (as long as they are serializable), participants in a distributed cluster concretely obey the distributed Protocol, which specifies request-response semantics using a well-defined message format.

Dedicated infrastructure in distributed handles the various aspects of the protocol, such as dispatching the various operations supported by an endpoint.


Worker, Scheduler, and Nanny objects all inherit from a Server class.

class distributed.core.Server(handlers, connection_limit=512, deserialize=True, io_loop=None)[source]

Distributed TCP Server

Superclass for endpoints in a distributed cluster, such as Worker and Scheduler objects.


Servers define operations with a handlers dict mapping operation names to functions. The first argument of a handler function will be a Comm for the communication established with the client. Other arguments will receive inputs from the keys of the incoming message which will always be a dictionary.

>>> def pingpong(comm):
...     return b'pong'
>>> def add(comm, x, y):
...     return x + y
>>> handlers = {'ping': pingpong, 'add': add}
>>> server = Server(handlers)  
>>> server.listen('tcp://')  

Message Format

The server expects messages to be dictionaries with a special key, ‘op’ that corresponds to the name of the operation, and other key-value pairs as required by the function.

So in the example above the following would be good messages.

  • {'op': 'ping'}
  • {'op': 'add': 'x': 10, 'y': 20}


To interact with remote servers we typically use rpc objects which expose a familiar method call interface to invoke remote operations.

class distributed.core.rpc(arg=None, comm=None, deserialize=True, timeout=3)[source]

Conveniently interact with a remote server

>>> remote = rpc(address)  
>>> response = yield remote.add(x=10, y=20)  

One rpc object can be reused for several interactions. Additionally, this object creates and destroys many comms as necessary and so is safe to use in multiple overlapping communications.

When done, close comms explicitly.

>>> remote.close_comms()  


Here is a small example using distributed.core to create and interact with a custom server.

Server Side

from tornado import gen
from tornado.ioloop import IOLoop
from distributed.core import Server

def add(comm, x=None, y=None):  # simple handler, just a function
    return x + y

def stream_data(comm, interval=1):  # complex handler, multiple responses
    data = 0
    while True:
        yield gen.sleep(interval)
        data += 1
        yield comm.write(data)

s = Server({'add': add, 'stream_data': stream_data})


Client Side

from tornado import gen
from tornado.ioloop import IOLoop
from distributed.core import connect

def f():
    comm = yield connect('tcp://')
    yield comm.write({'op': 'add', 'x': 1, 'y': 2})
    result = yield
    yield comm.close()

>>> IOLoop().run_sync(f)

def g():
    comm = yield connect('tcp://')
    yield comm.write({'op': 'stream_data', 'interval': 1})
    while True:
        result = yield

>>> IOLoop().run_sync(g)

Client Side with rpc

RPC provides a more pythonic interface. It also provides other benefits, such as using multiple streams in concurrent cases. Most distributed code uses rpc. The exception is when we need to perform multiple reads or writes, as with the stream data case above.

from tornado import gen
from tornado.ioloop import IOLoop
from distributed.core import rpc

def f():
    # comm = yield connect('', 8888)
    # yield comm.write({'op': 'add', 'x': 1, 'y': 2})
    # result = yield
    r = rpc('tcp://')
    result = yield r.add(x=1, y=2)


>>> IOLoop().run_sync(f)