The library and associated program is the basis for the Scyld Beowulf
mapping function.  Mapping is a term we use to describe one part of
scheduling.  It basically boils down to determine which nodes a job
would run on if it needed to run right now.

The goal is to supply the basic infrastructure with the hope that others
will write their own mappers depending on they're needs.

Doing your own mapping code
---------------------------

There are two ways to do your own mapping.  You can either write an
external program that sets the variable BEOWULF_JOB_MAP or you can
write a library that resolves the function "int get_beowulf_job_map
(const char *, int **)".

The BEOWULF_JOB_MAP variable should have a value of integers separated
by colons.  The value "-1:4:5" means run a three process job that uses
the master (-1) as the rank 0, node 4 as rank 1, and node 5 as rank 2.
You check yourself that each of the nodes is up and available to your
user and group ID.  You can run more than one job on a node with a
setting such as "1:1:1" which would run all three processes on node 1.

A little cleaner way of doing this is to write it to the library
interface.  Create a function with the prototype:

int get_beowulf_job_map(const char *caller, int **map);

"caller" is a string that tells who is calling you.  This might be
beomap, mpich-p4, or mpich-gm currently, but could be any sort of
value later.  I don't currently use this value in the default Scyld
scheduler (better_beowulf_sched), however, you might want to
differential in your scheduler based on this value.

The map should be an dynamically allocated array of integers
representing BEOWULF_JOB_MAP (as explained above) and the function
should return the number of elements in this array.

Before you get started I urge you to get a copy of the sources and
look at "simple_beowulf_scheduler.c" as a starting point.  In
particular, you'll probably want to use the sched_basic_setup()
function from sched_utils.c to handle the basic environmental variable
every mapping library should support.


Files
-----

The mapping code involves the following files:

 * sched_shim.c: This is generic code that should be used to call in
   the mapping code.  The purpose of this shim is: 
       - set a default master only mapping if something goes wrong.
       - check for BEOWULF_SCHED and handle dlopen if needed.
       - remember the returned mapping so the mapping code is only
          called once.
 
 * sched_utils.c: Contains most of the boilerplate you would probably
   want in every mapper and some useful utility functions.

 * simple_beowulf_scheduler.c: A simple example of how to do write a
   basic mapper.

 * better_beowulf_scheduler.c: The default Scyld MPICH mapping code.

 * beomap.c: A stand-alone program that will run the mapping code
   so you can peek at what the mapping would have been.

 * mpprun: A shell script to invoke the mapping code via beomap and
   distribute a non-MPI program across the cluster.
