# problem3.txt
# Dan R. K. Ports <drkp@mit.edu>
# 6.170 PS5, 2004/03/16
# $Id: problem3.txt,v 1.1 2004/03/17 01:25:20 dan Exp $

REQUIREMENTS

This implementation assumes that the simulator world will never be
modified (adding or removing pipes, filters, or edges, or defining
green groups) after simulation begins. The behavior is undefined if
changes are made after simulate() is called.

This implementation is also more general than the provided spec; it
allows an arbitrary number of lanes to be in a green group, not just
one or two.


DESIGN

The design of this class is very similar to that of CloverLeaf,
except for the addition of green groups. Green groups are tracked by
using a GreenGroup class that contains the duration and an ArrayList
of incoming lanes contained in the green group. It also contains the
minimum heading of the lanes, used for placing green groups in their
processing order. A greenGroups map is maintained, mapping
roadSegments to the associated GreenGroup record.

Each time simulate() is called, the TrafficLight selects the next
green group if the previous group's duration has expired, and
increments a clock variable with the duration of the timeSlice. Cars
are moved from input to output lanes in the same way as in a
CloverLeaf, except that only cars from lanes in the GreenGroup are
allowed to turn.

Starvation is still a concern, though only between lanes in a green
group. The choice of which lane to service first is made arbitrarily,
and the same lane will be chosen each time the green group is
simulated. Hence, the other lanes may be starved. As before, this can
be addressed by rotating the lane to be serviced first.


TESTING

A test suite was used to verify the correct operation of the methods
for manipulating green groups. The test suite generated a
TrafficLight intersection with several input and output lanes,
verified that the default assignments were sane, changed the duration
of green groups, and assigned multiple lanes to the same green group.

Testing of the simulate function could only be performed as an
integration test, since the TrafficLight depends on the Simulator and
its associated Lanes. The integration tests in TrafficTest were
sufficient to verify correct operation of the TrafficLight.


ANALYSIS

The TrafficLight class was successfully specified, designed,
implemented, and tested.

Some areas in which it could be improved: 

  - The TrafficLight needs to know when an incoming edge is added to
    the simulator, in order to place it in a default green
    group. Hence, a handler method (that does nothing by default) was
    defined in the Filter base class, called by Simulator, and
    overridden in TrafficLight. Though this is a general interface, it
    would be a good idea to make similar hooks available for other
    events, in order to provide for more general cases. 
 
 - Again, the implementation should be more resilient to calls that
    violate the @requires contract, throwing exceptions as
    appropriate.