• • Management of railway components
    • Trains
    • Tracks
    • Contacts
    • Stations
  • Rulesets
    • Logging
    • Codestyle
    • Deadlock Prevention

Management of railway components

Trains

• Each train has a trainnumber.
  
  • Apart from identification the trainnumber is used for prioritization, when multiple trains compete for the same track.
  • Lower numbers mean higher priorities, e.g. train 0 has the highest priority.
  • Priorities can't be changed dynamically.
• Each train has one home-track.
• For binding purposes the variable should have the name trainNum.

The numbering is derived from the initial positions of the trains.

Tracks

• Stopping on tracks without contacts is not allowed!
• Tracks without contacts must be reserved and used with an adjacent "safe" track.
• When requesting multiple locks, deadlocks must be prevented
• Three different speed settings are available, adjusted to the individual trains:
  • NORMAL - Normal driving speed
  • CAUTION - Speed when slowing down while waiting for permissions (and optionally for branch points)
  • SLOW - Driving into a station

Contacts

• Contact events should only be read when it is clearly determined which train will trigger this event.
• Subsequently contact events should only be read while holding the corresponding lock.

Stations

• Each station has one drive-through track for each possible direction:

• If the preferred station track is blocked the trains can switch to any other free track.
  While cleanup is active the trains on IC_ST_1, OC_ST_3 or KH_ST_1 circle until all tracks are done.

Rulesets

Logging

• All log messages must be prefixed. For Station-2-Station controllers the prefix [trainnum][ST-ST] must be used.
• The variable debug indicates verbose logging.
• Station-2-Station controllers should produce a log message when entering a new train segment even without verbose logging.
• With verbose logging every state can produce a log message as an entry action.
• Function println(String str) must be used to produce textual output.
• printf() or other IO functions must not be used, because output may not be flushed correctly.

Codestyle

• Use entry-/exit-actions instead of actions on transitions, if possible.
• If using hostcode, only use functions delivered by our own C-Interface and not the Höhrmann-API.

Deadlock Prevention

• When attempting to reserve more than one segment (entering a station, passing a junction) a separate protocol for deadlock prevention must be adhered to.
• In each tick the controller must check if only partial permissions were granted.
• If partial permission was granted the train waits for one tick and releases all locks.
• In the following tick the locks are requested again.
• As a special case the controllers passing through KIO_LN_0 or KIO_LN_1 must wait an additional tick after releasing the requests.
• Another special case for the KHIC-Controller: A train is at KIO_LN_0 and requests OC_ST_4, IC_ST_0 and the tracks of the IC-Station. If the train gets the permission for OC_ST_4 but not for IC_ST_0 and any of the tracks of the IC-Station, the controller waits for an additional tick before re-requesting, so that a train with a lower priority, which travels along the OC-Circle, can pass. It was observed, that this change makes the traffic more fluent.
• A sample controller can be found in the repository at /doc/deadlocks/resolve_deadlock.sct 
• Further deadlock avoidance is implemented in the ICKHS and OCKHS controllers. If the circle ICKH-KHIC-Circle (OCKH-KHOC-Circle) is full (which means, that all trains have the status "brake"), then one of the trains travels the IC-Circle (OC-Circle), to unlock the deadlock. Our tests have shown, that it is still possible, that the same train has to unlock the deadlock again, so that it never reaches its destination, but at least the other trains reach their destination. This concept could also be adapted to the OCOC and ICIC controllers. Use with care, as these controllers have not been tested to exhaust. Basically the controller wraps the ICKH and ICIC (OCKH and OCOC) controller. If the circle is full (checked at hostcode.c), the slightly changed ICKH (OCKH) controller is aborted or not even started, and instead, the ICIC (OCOC) controller is started. At the hostcode.c file, there is an array, which keeps track of the status of all tracks, where 0 means OFF, 1 means REV or FWD and 2 means BRAKE. To keep it simple, the tracks, where the 11-trains are initially standing are initialized with 2.