NOTE: unless otherwise noted, the references below point to specific sections and figures in the on-line technical report available at:


These instructions assume an Unix-like operating system with Java 8 as default JRE/JDK. They have been tested on Ubuntu (14.04 and 15.10), Debian GNU/Linux (Sid, April 2016), and Mac OS X (10.10 and 10.11). They should also work on Windows with minor adaptations.

For some examples, and to generate the benchmark plots, you will also need Python 2.7.x and matplotlib.

Initial setup on Ubuntu (14.04 and later)

If you use Ubuntu (or recent versions of Debian GNU/Linux), this section provides detailed instructions that should be followed before compiling the sources.

  1. If you are using Ubuntu 14.04, you might first need to enable the software repositories for Java 8. Open a terminal and execute the following commands:
    sudo add-apt-repository ppa:openjdk-r/ppa   # Not needed on Ubuntu ≥ 14.10
    sudo apt-get update                         # Not needed on Ubuntu ≥ 14.10
  2. On all Ubuntu/Debian versions, you need to ensure that Java 8 is installed and selected as the default JRE/JDK. Thus, you should execute the following commands:
    sudo apt-get install openjdk-8-jdk          # Alternatively: oracle-java8-jdk
    sudo update-alternatives --config java      # Ensure that Java 8 is selected
    sudo update-alternatives --config javac     # Ensure that Java 8 is selected
  3. Moreover, in order to generate the benchmark plots, you might also need to execute:
    sudo apt-get install python-matplotlib

Compiling the sources

  1. You will need sbt 0.13.x: the installation instructions for various OSs are available here.
  2. Open a terminal, and cd inside the lchannels/ directory. NOTE: from now on, all commands must be launched from this position.
  3. Execute the following command:
    sbt compile
    This will cause sbt to automatically download all missing dependencies (including Scala 2.11.8) and compile lchannels.


To launch the examples, execute:

sbt "project examples" run

You will get a prompt similar to the following:

Multiple main classes detected, select one to run:

 [1] lchannels.examples.calc.Local
 [2] lchannels.examples.calc.Queue
 [10] lchannels.examples.greeting.ActorClient
 [11] lchannels.examples.greeting.ActorServer
 [12] lchannels.examples.greeting.Local
 [13] lchannels.examples.greeting.Queue
 [14] lchannels.examples.greeting.SocketClient
 [15] lchannels.examples.greeting.StreamClient
 [16] lchannels.examples.http.server.Server
 [17] lchannels.examples.scribblegreeting.ActorClient
 [18] lchannels.examples.scribblegreeting.ActorServer
 [19] lchannels.examples.scribblegreeting.Local
 [20] lchannels.examples.scribblegreeting.SocketClient
 [21] lchannels.examples.sleepingbarber.demo.Local
 [22] lchannels.examples.threebuyer.alice.Actor
 [23] lchannels.examples.threebuyer.bob.Actor
 [24] lchannels.examples.threebuyer.carol.Actor
 [25] lchannels.examples.threebuyer.demo.Local
 [26] lchannels.examples.threebuyer.seller.Actor

Enter number:

The prompt allows to choose among:

Running the examples

Browsing the source code

The source code for all examples can be found under examples/src/....

The main differences wrt. the code snippets in the technical report are the addition of log messages, and in some cases the presence of parameters that were omitted for simplicity of exposition. For instance:


The benchmarks (§6.2 of the technical report) can be run by executing:


The command above launches a reduced version of the benchmarks, that should terminate pretty quickly.

If you want to replicate the measurements in §6.2 of the technical report (which take much longer and can be stressful for the Java GC) you can execute instead:

./scripts/ 10 2000000   # Meaning: 10 JVM invocations, ~2000000 message exchanges

In both cases above, you will obtain:

The source code for the benchmarks can be found under benchmarks/src/....

API documentation and source code pointers

The API documentation for lchannels is automatically generated from source code comments, with:
sbt "project lchannels" doc

After running the command above, the documentation can be browsed by opening lchannels/target/scala-2.11/api/index.html. For reference, a (possibly outdated) copy of the documentation is also available online (last update: May 3, 2016).

Here are some selected links:

Some other features and details:

Miscellaneous remarks