T-106.420 assignment 1 — Trains

In this assignment, you will practise mutual exclusion using semaphores, the basics of writing multithreaded Java programs and communicating with external entities through a prewritten interface.

The assignment 1 lecture slides summarise the assignment. Note that this page is the authoritative description of the task requirements, not the lecture slides.

Background

A small railway company is looking for a way to automate their train control in order to downsize their staff and improve safety. You have been tasked with implementing the train control software. However, the company executives do not want to take any chances with their trains. For this reason, they want you to write control software for two trains on a simulated track as a proof of concept (and your skills). The functioning of the simulation and how convincingly you can argue that it works correctly will strongly affect your chances of getting a multi-million Euro contract.

Task description

Your task is to write a Java program that controls two trains travelling between the two stations of a specific track in the tsim train simulator. All the required files can be found in Niksula in ~jlonnber/tsim and in the tsim installation package. To start tsim in Niksula, run ~jlonnber/tsim/tsim <track>, where <track> is the track you want to load into tsim (~jlonnber/tsim/track contains the track used in this assignment). In order to complete this task, you must:

Add sensors to the track.
Write code that receives sensor events and sets the speed of a train and the state of switches based on these events.

Train behaviour requirements

The trains must travel from one station to another until the simulator or train control program is terminated. They must be stopped for a randomly chosen (from a uniform distribution) time of (roughly) 2 to 8 seconds at each station (don't worry about the exact time, as long as you have at least 4 seconds of variation and the train is stopped for at least a second). Obviously, the trains must not collide with each other, derail or run into the stops at the ends of the track. The trains should move between stations with few delays and good speed (a train should not need more than 3 minutes per round trip), but fine-tuning the trains to cut every possible millisecond off their travel time is not the goal of this assignment. You need not take into account user interaction with the simulator through its GUI.

Train behaviour may not depend on the id of the train. In particular, this means that both trains should use the same code. The trains should use the upper track at the stations and the shorter track halfway between the stations if the other train is not in the way.

Your trains should behave correctly when the default acceleration and time step values are used; you do not need to support any other values for these parameters.

Track requirements

You may add sensors as required to the track. However, you may not modify the track in any other way. You may not change the initial position of the trains, add or remove trains or change their length. All tests of your code will be run with the track you submit, although the train ids may be reversed. The purpose of this exercise is not to write a solution that works on any track; that is a much harder problem.

Concurrency and synchronisation requirements

Each train must be controlled by a separate thread that uses the tsim Java API to control the speed of the train, flip switches and receive sensor events for the train. Semaphores are the standard synchronisation technique for rail traffic, so the train threads may only communicate with each other using sync.Semaphores (see the sync directory in the tsim package or ~jlonnber/tsim/sync in Niksula). The trains must both use the same code and base their actions solely on sensor events and semaphore states. In particular, the train ids should not affect their behaviour.

Inefficient solutions, such as polling and busy-waiting, will be rejected.

Style requirements

The program should be written in clear, object-oriented Java. We will not accept programs that are hard to read, have a noticeably non-OO style or contain a large amount of repeated code with minor variations. Cryptic method and variable names should not be used.

Explanatory comments are required for code that is not self-explanatory to a programmer fluent in Java. However, you should not clutter your program by stating the obvious. As an example, Javadoc comments describing the syntax of trivial methods (such as accessors) will be tolerated but are discouraged.

Execution

Your program must contain a class trains.Train whose main method starts a train thread for each of the two trains and drives them from station to station as described above, when run in a virtual machine whose standard output and input are connected to tsim. In other words, your solution should start running (assuming Java is in the path and your solution and the tsim package are in the current directory) on Unix with the command:

./2 "cd tsim-0.7; ./tsim
../track-sensors" "java
trains.Train"

On Niksula machines, your solution should run using the command:

~jlonnber/tsim/run

Documentation

You must provide a PDF file in which you explain how your solution works. In particular, you should explain the reasoning behind your placement of sensors and how your trains co-ordinate their use of the track. The documentation should not contain a line-by-line explanation of the implementation; an explanation of the structure of the implementation is sufficient.

Language

Comments, variable and method names and documentation may be written in English, Swedish or Finnish. You should avoid mixing these languages, but you may use different languages for different aspects of the assignment (e.g. code in English and comments and documentation in Swedish is fine).

Hints

You have no way of telling how fast your train is going except dead reckoning (it accelerates at 5.0 pixels/second² until it reaches the set speed) and previous speed change commands. When stopping and turning, take into account that your train may be travelling at anything between 0 and maximum speed unless you have given it enough time to accelerate/decelerate to the right speed.
tsim is running in a separate process. This means that the trains will continue to move at the speed your code has given them irrespective of what your code is doing. Don't expect the trains to wait while your code figures out what to do.
Interprocess communication may introduce delays, so don't cut the braking distances too fine.
The trains travel forwards and backwards equally well, and you can't turn them around on this track.
Make sure you only create only one TSim.TSimInterface. Accidentally creating two of these is very likely to cause sensor events to be lost.
Slowing down one of your trains or manually stopping it helps you find problems quicker. Overriding your trains' speeds through the tsim GUI may, of course, mess up your synchronisation code, so don't panic if something goes wrong when you do that.
The try_acquire method in sync.Semaphore will help you keep things running smoothly (or at least smoother).
You can use System.err for debug output. Sending output to System.out will confuse tsim.
This example train implementation drives one of the trains from one station to another and back on this track with sensors. You can use this as a basis for your solution.

Submission

Before the deadline (2005-11-16 03:00), you must submit a gzipped tar archive containing your solution using the form below. The archive must contain the following files:

`trains/`	The Java (version 1.4 or earlier) source code of your train control program (the directory corresponds to the `trains` package).
`track-sensors`	The supplied track with your sensors added.
`description.pdf`	A PDF containing the documentation for your solution.

Your program will be compiled and run with the simulator Java interface and standard library included in the classpath.

You may work in pairs. The grading does not depend on whether you are working alone or in a pair.

Results will be sent to both students at <student number>@students.hut.fi.

Page last updated by Jan Lönnberg 2005-10-30.