Princeton University
COS 217: Introduction to Programming Systems

Assignment 4: A Kalah Referee

Purpose

The purpose of this assignment is to help you learn about processes and inter-process communication. It will also give you more experience with advanced C programming, creating and using ADTs, and the GNU/UNIX programming tools.

Your Task

This assignment is a follow-on to the previous one. Your task in this assignment is to create a Kalah referee program that can launch and monitor the execution of two competing Kalah player programs. More specifically, your job is to create code which, when combined with portions of your team's Kalah player code from the previous assignment, implements a Kalah referee program.

The Kalah Referee Functionality

Your Kalah referee should accept two command line arguments:

The name of the executable file that contains the MIN player program.
The name of the executable file that contains the MAX player program.

Your Kalah referee should keep track of the state of the game so it knows whose move is next, when the game is over, and who won.

Informally, your Kalah referee should use this algorithm:

Set the "current" Kalah player to be the MIN player.
Read a move from the current Kalah player.
Display the move to stdout.
Verify that the move is valid, and end the game if it is not.
Update its game state with the move.
Display its game state to stdout.
Write the move to the other Kalah player.
Determine which Kalah player is now the current one.
Repeat steps 2-8 until the game is over, and then...
Write an indication of who won to stdout.

Your Kalah referee should insure that neither Kalah player consumes more than 2 minutes of CPU time.

For simplicity, your Kalah referee need not detect when a Kalah player has crashed. Suggestion: Enhance your referee so it does detect when a player has crashed.

The Kalah Referee Design

Your Kalah referee should use the pipe system call to create pipes through which it communicates with the Kalah players. It should use the fork system call to create child referees, and the execvp system call to overlay each child referee with a player. It should use the close and dup (or dup2) system calls to redirect stdin and stdout of each player so the player writes moves to the referee through a pipe, and reads moves from the referee through a pipe.

Your Kalah referee should use the setrlimit system call to set the CPU limit for each player. More precisely, before overlaying itself with a player, each child referee process should call setrlimit to limit the amount of CPU time that the process may consume to 2 minutes.

After a failed system call, your Kalah referee should use the perror function to print an indication of what went wrong to stderr.

Suggested enhancement (for no extra credit): Design your Kalah referee so it uses the UNIX signal and alarm functions to detect when a player has crashed, and then declares the winner and ends the game.

Logistics

This is not a team assignment; you should create your Kalah referee on your own. However, you should feel free to use the Kalah player code that your team created in the previous assignment. You may ask any of your teammates for Kalah player code; if a teammate asks you for your Kalah player code, you should provide it. You should only get Kalah player source code from other people after you have submitted your own Kalah player program for a grade.

You should develop on arizona. Use Emacs to create source code. Use the "make" tool to build. Use gdb to debug.

Recall that a sample executable Kalah referee program is available in file /u/cs217/Assignment3/samplekalahreferee. You may use it to answer questions about the desired functionality of your Kalah referee.

You should submit:

A complete set of source code files for your Kalah referee. That set should include your Kalah referee source code file(s), and will probably include some files that were created by your team for the previous assignment.
A makefile that uses those source code files to build an executable file named kalahreferee. The first rule in the makefile should build kalahreferee using the "-Wall," "-ansi," and "-pedantic" options.
A readme file.

Your readme file should contain:

Your name.
A description of whatever help (if any) you received from others while doing the assignment, and the names of any individuals with whom you collaborated, as prescribed by the course "Policies" web page.
(Optionally) An indication of how much time you spent doing the assignment.
(Optionally) Your assessment of the assignment.
(Optionally) Any information that will help us to grade your work in the most favorable light. In particular you should describe all known bugs.

If you can reuse some of the kalah player files from the previous assignment completely unchanged, so much the better. Please mention in your readme whether this was possible.

Submit your work electronically via the command /u/cs217/bin/submit 4 sourcecodefiles makefile readme.

Grading

As always, we will grade your work on functionality and design, and will consider understandability to be an important aspect of good design. To encourage good coding practices, we will take off points based on warning messages during compilation.

We will test your work by using your makefile and source code files to build kalahreferee. We will then use your kalahreferee to conduct games between two instances of samplekalahplayer.

Princeton University COS 217: Introduction to Programming Systems