Before you begin the assignment, log into spinlock or coredump, and copy the following file into your directory:
/cse451kernels/gribble/fairshare.tar.gz
This tar archive contains the source code and binaries of a number of utilities that you will find useful during the course of this project. We'll describe them below. To extract the files from the archive, use the following command:
tar -xvzf fairshare.tar.gz
A directory called fairshare/ will be created, and the utilities will be extracted into it.

Project Utilities Overview

You'll be working on the scheduler.  If the systems hangs or crashes, you'll know your changes haven't worked.  But, how will you know that they are working?

We've written some utility programs to help with this.  These might be of some use in looking at how the existing scheduler behaves, but are intended primarily to help evaluate your changes.  The source to the utilities is available, but they were written with the intention that you'd never have to look at it.  The source can be used to install the utilities on Linux machines outside of the lab (they're already installed in the lab), or to customize the utilities if you want them to do things they don't already do.

There are two major utilities, one that shows a full-screen display of the fraction of CPU allocated to each user and each user process, and one to help launch a set of applications as if they were launched by a set of distinct users.

Monitor Utility

Command:  monitor [refresh interval in seconds]

The monitor prints a full screen display showing CPU usage by all user-level (not root, and not a few daemon) processes.  The display is updated every "refresh interval" seconds, defaulting to 2 seconds if no parameter is given.  (2 seconds is also the minimum interval allowed.)  

Here is some sample output:

Elapsed time: 2.13 seconds

zahorjan: 100% ( 99%, 0%)
( tcsh) 18122 0% ( 0%, 0%)
( piglet) 18168 99% ( 99%, 0%)
( monitor) 18170 0% ( 0%, 0%)

The first line shows the amount of real time that passed between screen updates.  The next line shows that user zahorjan consumed 100% of CPU the during those 2.13 seconds.  zahorjan was running three processes, a shell (with PID 18122), a process called piglet, and the monitor itself.  The piglet process used the CPU for 99% of the 2.13 seconds, of which 99% of the 2.13 seconds was in user mode and 0% was system mode.  (Conversion to integers in the monitor program, as well as the Heisenberg principle, cause some loss of precision.)

The monitor program accepts two keyboard inputs.  The inputs are acted upon only the next time the screen is updated (for reasons that you can guess from the original client code in project assignment two).  The inputs are:

'q' Quit the program
<space>  Toggle between real-time and CPU time modes

The sample output explained above is real-time mode: fractions are given relative to the actual elapsed time between refreshes of the screen.  In CPU time mode fractions are relative to the total amount of CPU used during that interval.  So, if the refresh interval were exactly 2 seconds and some one process were the only one that ran during that time, and it used 1 second of CPU, it would show 50% consumption in real-time mode and 100% consumption in CPU mode.

Spawn Utility and Its Cronies

Command: spawn [configuration file]

The spawn command reads a configuration file, each line of which specifies a user ID (UID) and the name of an executable.  It forks a new process for each line and runs the named executable in it.  It also sets the UID of the process to the value given in the line of the configuration file.  This allows you to launch a set of processes as if they had been launched by a set of distinct users.  Because spawn sets the UID of processes, you must be logged in as root to use it.

Two sample executables are also provided, piglet and io.  Piglet is just a tight CPU loop.  Io is a program that reads every file on the system (that is accessible to the UID of the process).  The io program is thus very IO bound, and not at all CPU bound.

A sample configuration file, spawn.conf, has also been provided.  It's contents are:

9000 piglet
9000 piglet
9000 piglet
9001 piglet
9001 piglet

When spawn reads this file it will launch five copies of the piglet program, three as user 9000 and two as user 9001.  (These UIDs were chosen because they do not conflict with any real users on the SPL machines.)  Here is output from the monitor program after launching spawn with this configuration file:

Elapsed time: 2.12 seconds

zahorjan:  0% ( 0%, 0%)
( csh) 7760 0% ( 0%, 0%)
( csh) 7847 0% ( 0%, 0%)
( monitor) 7868 0% ( 0%, 0%)
User 9000: 60% ( 60%, 0%)
( piglet) 7840 19% ( 19%, 0%)
( piglet) 7841 20% ( 20%, 0%)
( piglet) 7842 20% ( 20%, 0%)
User 9001: 39% ( 39%, 0%)
( piglet) 7843 19% ( 19%, 0%)
( piglet) 7844 19% ( 19%, 0%)

(The two new user names show up as "User UID" because there is no actual user name for those UIDs on that system.)

Exactly what spawn does is a tiny bit complicated, but it's designed to work almost whatever it is you're trying to do.  So, you don't have to understand the next paragraph - it should just work.

The complication has to do with where (a) the configuration file is, and (b) where the executables named in the configuration file are.  The rules are this:

  1. If no configuration file is given on the command line, the file is assumed to exist in the same directory as the spawn executable, and to be named spawn.conf.

  2. If a configuration file name is given, if the path is absolute (e.g., ~/FairShareProject/myspawn.conf), that's used.  If the path is not absolute (e.g., myspawn.conf), it's relative to the current working directory. 

  3. Executable file names in the configuration file can be either absolute path names or relative names.  If relative, they are relative to the directory in which the configuration file was found.

One last thing.  The spawn program includes one additional function:  it kills everything it has spawned after 2 minutes.  This is intended to be a convenience, in case you forget to kill something that is either in a tight CPU loop or reading the entire file system.  It is easy to change the 2 minute interval to something else, if you want, or to defeat this entirely.

One other last thing.  There is absolutely no reason to run piglet or io on any machines besides VMware virtual machines (or your own, if you're working at home), and you should never run them on any shared machine.  This includes all four general purpose instructional machines (ceylon, fiji, sumatra, and tahiti), as well as spinlock and coredump.