STaRS - A Scalable Task Routing approach to distributed Scheduling
------------------------------------------------------------------

STaRS is a distributed scheduler of bag-of-tasks applications. It creates a
P2P overlay for the distribution of tasks among execution nodes, following
arbitrary policies. Its main goal is to reach scales not provided by any other
similar project.

It is currently in pre-Alpha stage, only simulation is possible.


License
=======

STaRS is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

STaRS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details. A copy of the license
is included in the file LICENSE; if not, see <http://www.gnu.org/licenses/>.


Compilation
===========

STaRS depends on the following software:

- CMake 2.6 or higher
- Boost libs 1.46 or higher
- Log4CPP
- MsgPack (tested with v. 0.5.7)

Optionally, some parts are also compiled with the following software:

- SimGrid 3.6 or higher
- Wt 3.2 or higher

The build system uses a mix of GNU make and CMake. CMake should be able to
find the required libraries if they are in common locations, like /usr or
/usr/local. In order to build a certain CMake build type, issue:

$ make CONFIG=type

Where type is one of Debug, Release, RelWithDebInfo of MinSizeRel. It
defaults to Debug. This is the same as:

$ mkdir -p build/type
$ cd build/type
$ cmake ../.. -DCMAKE_BUILD_TYPE:STRING=type
$ make

Usage
=====

TODO


Simulation
==========

Currently, only the ad-hoc simulation engine (in directory oldsim) is fully
usable. The version based on SimGrid is still under development, and not built
by default.

The simulator substitutes all the code related to networking and
time management, and some other parts that are not relevant for the performance
analysis, like database access. It also provides those parts that are not yet
implemented or in an experimental state. It is invoked with the command:

$ stars-oldsim config_file

The config_file is a file with a set of properties in the form of key=value,
one per line. The special key case_name defines the case to be executed. Then,
each case has some specific properties and the rest are common to the
simulation platform. See the examples for further explanation. The configuration
can also be fed from standard input:

$ stars-oldsim - < config-file

Tools
=====

The sweeper tool can be used to generate a set of configuration files for
parameter sweep simulations. It is invoked as:

$ sweeper config_file

The config_file file is similar to the configuration file of the simulator,
but special notation is used to assign lists and sequences of values to a
single key. The sweeper command generates a simulator configuration file for
each possible combination. See the examples for further explanation.

Additionally, the sweeperdaemon tool listens on a named pipe for simulation
configurations and launches the simulator automatically. It is invoked as:

$ sweeperdaemon -e path_to_simulator [-f pipename] [-p num_proc] [-m max_mem]

The mandatory argument is the path to the simulator executable. The tool
creates the named FIFO 'pipename', if needed. If 'pipename' is not provided,
'sweeperpipe' is used by default. num_proc is the number of concurrent
processes that can be launched. Should be equal to the number of cores.
max_mem is the maximum physical memory to be used by the simulations. This avoids
the undesired situation in which a simulator process needs to use swap memory.

Once the simulation has ended, the cdf tool will generate the cummulative
distribution function for several results. Just invoke the tool with the results
directory as argument.