Skip to content

Docker

Prerequisites

  • a windows/linux/mac machine with docker installed.

Info

Apple's M1/M2/M3-based machines are now supported.

Warning

This docker environment is primarily for testing and is not supposed to be used for performance runs. For performance runs, see the clusters/supercomputer section.

Download the Dockerfile

Currently, there are two versions of Dockerfile: one is based on the latest version of the bale library (3.x) and another is based on bale 2.x. We would recommend using the bale3 version unless there is a specific reason to use bale_old version.

Build the Dockerfile

docker build -t actor -f Dockerfile .

Note

For more details on docker build, please see the official document

Run the container

docker run -it actor /bin/bash

Note

For more details on docker run, please see the official document

Tip

Once you run the container, you can safely exit from it and may want to stop it by doing docker stop unless you gave the --rm option to the docker run command, which destroy the container when you exit. When you resume, you first need to make sure the status of the container by doing docker ps -a: 

// On the host
$ docker ps -a
CONTAINER ID   IMAGE           COMMAND       CREATED         STATUS                       PORTS                    NAMES
145199093e17   actor           "/bin/bash"   3 weeks ago     Exited (0) 2 weeks ago                                ecstatic_snyder
a831e3f73cec   actor           "/bin/bash"   15 months ago   Up 27 hours                                           priceless_franklin

If the container is "Up", you can attach to it by doing docker exec -it [CONTAINER NAME] /bin/bash. In this example, priceless_franklin is up and you can attach to it by doing docker exec -it priceless_franlkin /bin/bash. Otherwise, you first need to start the container by doing docker start [CONTAINER NAME].

Within the container, the following environment variables are defined

Var Value Description
LOCAL /root/local The location of the OpenSHMEM toolchain is installed
CC /root/local/bin/oshcc The OpenSHMEM C compiler
CXX /root/local/bin/oshc++ The OpenSHMEM C++ compiler
OSHRUN /root/local/bin/oshrun The OpenSHMEM launcher
BALE_INSTALL /root/bale/build_unknown The location of the Bale library
HCLIB_ROOT /root/hclib/hclib-install The location of the HClib
LD_LIBRARY_PATH LD_LIBRARY_PATH=$LOCAL/lib:$BALE_INSTALL/lib:$HCLIB_ROOT/lib:$HCLIB_ROOT/../modules/bale_actor/lib The locations of static/dynamic libraries
HCLIB_WORKERS 1 The number of HClib workers per each PE

Warning

Do NOT change the value of HCLIB_WORKER. In the current implementation, we exploit the OpenSHMEM PE-level parallelism, where each PE is associated with a physical/virtual CPU core, and creating multiple workers per PE can degrade the performance and cause an error.

Run the histogram example

Now that the container is running, let's build and run the selector version of the histogram benchmark. You can make it by doing make histo_selector and launch it with 2 PEs using $OSHRUN. 

// move to "test" directory
cd ../test
// build a selector version of histogram
make histo_selector
// run it on 2PE using $OSHRUN
$OSHRUN -n 2 ./histo_selector -n 100

Example Output: 

WARNING: Failed dynamically loading /root/hclib/hclib-install/lib/libhclib_bale_actor.so for "bale_actor" dependency
WARNING: HCLIB_LOCALITY_FILE not provided, generating sane default locality information
WARNING: HCLIB_WORKERS provided, creating locale graph based on 1 workers
WARNING: Failed dynamically loading /root/hclib/hclib-install/lib/libhclib_bale_actor.so for "bale_actor" dependency
WARNING: HCLIB_LOCALITY_FILE not provided, generating sane default locality information
WARNING: HCLIB_WORKERS provided, creating locale graph based on 1 workers
Running histo on 2 threads
buf_cnt (number of buffer pkgs)      (-b)= 1024
Number updates / thread              (-n)= 100
Table size / thread                  (-T)= 1000
models_mask                          (-M)= 0
     0.019 seconds

Note

Recall that OSHRUN is an environment variable and do not forget to add the dollar sign ($) before OSHRUN.

Note

Lambda versions may not work on the docker environment due to the address space layout randomization.