||                                                                            ||
||                      Distributed Shared Memory Library                     ||
||                Robert Gasparyan, Angela Gong, Judson Wilson                ||
||                                                                            ||

+-------------------------------- ENVIRONMENT ---------------------------------+

The application must be done in a Linux environment. It has been tested on
Ubuntu 14.04, and the Stanford corn machines.

ASLR needs to be turned off, via the following command:
  setarch $(uname -m) -RL bash

All 'cd' commands will be based off of the home directory, 'dsm', which we will
refer to as '~' from now on.

+---------------------------------- CONTENTS ----------------------------------+

1. Directory Contents
2. Example Application
3. Deployment
4. Creating an Application with DSM
5. Running Tests
6. Benchmarks

+---------------------------- DIRECTORY CONTENTS  -----------------------------+

  ~/Makefile       - Makefile for the libray, the internal library, and deploy.
  ~/README         - This file.
  ~/benchmarks     - Benchmark tests.
  ~/deploy         - The deployment system.
  ~/lib            - The actual DSM library, source, include, etc.
  ~/libdsminternal - Internal library. Common code for this library, and deploy.
  ~/toys           - Simple programs we used to test out ideas.

+---------------------------- EXAMPLE APPLICATION -----------------------------+

We've provided a reference program, called 'reference'. This demonstrates
how to use the DSM library at a very basic level, and the deploy system.
It simply uses locks to implement an atomic counter, and has each host
perform an increment and print the value.

The source, tests, and README are located in ~/lib/tests/reference

Compile the DSM Library
First you'll have to compile the library and the deploy system.

    make clean

Running the Reference Program
The reference program is located at lib/tests/reference/reference.c. You can
build it by:

    cd ~/lib/tests/reference
    make clean

You'll need to open two terminal windows on the same host to run the app.
Make sure you start testh2.sh AFTER testh1.sh, etc.

    Terminal 1                        Terminal 2
    ----------                        ----------
    cd ~/lib/tests/reference/host1

    [ Deployer will now run with ]
    [ deployer> prompt. Type the ]
    [ following in:              ]

                                      cd ~/lib/tests/reference/host2

    deploy reference

Both terminals should now spit output. One should say:

  I just incremented counter to 1

the other should say:

  I just incremented counter to 2

To run on multiple hosts, see lib/tests/reference/README

+--------------------------------- DEPLOYMENT ---------------------------------+

We've provided a deployment application that will deploy binaries to different
machines. All the code is in ~/deploy.

First you need to start the master server.

    cd ~/deploy
    ./dsm_server -n [num_daemons] -p [port_number]

On NUM_DAEMONS different machines, start the daemon.

    cd ~/deploy
    ./dsm_daemon -s [machine_where_server_is] -p [server_port]

On the master server, the following prompt will appear. You can type in two
commands. 'deploy programname args' will deploy a binary called programname
to all daemons with the arguments args. It will also append any args needed
for the DSM system. 'exit' will exit.

    deployer> deploy reference

+--------------------- CREATING an APPLICATION with DSM -----------------------+

More information is provided in ~/lib/README, and the reference program (above)
is a great example to get started.

+------------------------------- RUNNING TESTS --------------------------------+

Deployment Test
We typically use the test located in ~/deploy/test, although the deployment
test for the reference example above is substantially identical, with
more documentation.

"lock_races" Test
This is the main test for our DSM library. It checks for race-condition
behavior and deadlocks, by looping over many locking patterns on 3 hosts,
then verifies that the values in shared memory are correct.

For more information, please see the README and code in ~/lib/tests/lock_races

+--------------------------------- BENCHMARKS ---------------------------------+
Word Count:

This benchmark is meant to be very I/O intensive. It implements a bloom filter
for doing a word count on a large text corpus(30 text files).

1. cd benchmarks/word_count
2. make
3. ./get_files.sh  //To generate text files

Follow directions in DEPLOYMENT to deploy word_count_dsm

Matrix Multiply:

This benchmark is meant to be very CPU intensive. It implements a matrix
multiplication by computing each part of the final matrix in a separate thread.

1. cd benchmarks/matrix_mult
2. make

Follow directions in DEPLOYMENT to deploy matrix_mult_dsm