Interfaces and Rulesets

* When attempting to reserve more than one segment (Entering a station, passing a junction) a separate protocol for deadlock prevention must be adhered to.

156

* In each tick the controller must check if only partial permissions were granted.

157

* If partial permission was granted the train waits for one tick and releases all locks.

158

* In the following tick the locks are requested again.

159

* As a special case the controllers passing through KIO_LN_0 or KIO_LN_1 must wait an additional tick after releasing the requests.

160

* A sample controller can be found in the repository at [[/doc/deadlocks/resolve_deadlock.sct>>url:https://git.rtsys.informatik.uni-kiel.de/projects/PRAK/repos/14ss-railway/browse/doc/deadlocks/resolve_deadlock.sct||shape="rect"]]

Wiki source code of Interfaces and Rulesets

Navigation

Quick Links

author	version	line-number	content
		1
		2
		3	{{toc/}}
		4
		5	== Management of railway components ==
		6
		7	=== Trains ===
		8
		9	* Each train has a trainnumber.\\
		10	** Apart from identification the trainnumber is used for prioritization, when multiple trains compete for the same track.
		11	** Lower numbers mean higher priorities, e.g. train 0 has the highest priority.
		12	** Priorities can't be changed dynamicly.
		13	* Each train has one home-track.
		14	* For binding purposes the variable should have the name trainNum.
		15
		16	The numbering is derived from the initial positions of the trains.
		17
		18	\|=(((
		19	trainNum
		20	)))\|=(((
		21	Starting track
		22	)))
		23	\|(((
		24	0
		25	)))\|(((
		26	KH_ST_1
		27	)))
		28	\|(((
		29	1
		30	)))\|(((
		31	KH_ST_2
		32	)))
		33	\|(((
		34	2
		35	)))\|(((
		36	KH_ST_3 (r)
		37	)))
		38	\|(((
		39	3
		40	)))\|(((
		41	KH_ST_4 (r)
		42	)))
		43	\|(((
		44	4
		45	)))\|(((
		46	IC_ST_3
		47	)))
		48	\|(((
		49	5
		50	)))\|(((
		51	IC_ST_2
		52	)))
		53	\|(((
		54	6
		55	)))\|(((
		56	OC_ST_2
		57	)))
		58	\|(((
		59	7
		60	)))\|(((
		61	OC_ST_1
		62	)))
		63	\|(((
		64	8
		65	)))\|(((
		66	KH_ST_5
		67	)))
		68	\|(((
		69	9
		70	)))\|(((
		71	IC_ST_1
		72	)))
		73	\|(((
		74	10
		75	)))\|(((
		76	OC_ST_3
		77	)))
		78
		79	=== Tracks ===
		80
		81	* Stopping on tracks without contacts is not allowed!
		82	* Tracks without contacts must be reserved and used with an adjacent "safe" track.
		83	* When requesting multiple locks, deadlocks must be prevented
		84	* Three different speed settings are available, adjusted to the individual trains:
		85	** NORMAL - Normal driving speed
		86	** CAUTION - Speed when slowing down while waiting for permissions (and optionally for branch points)
		87	** SLOW - Driving into a station
		88
		89	=== Contacts ===
		90
		91	* Contact events should only be read when it is clearly determined which train will trigger this event.
		92	* Subsequently contact events should only be read while holding the corresponding lock.
		93
		94	=== Stations ===
		95
		96	* --Each station has one drive-through track for each possible direction:--
		97
		98	\|=(% style="margin-left: 60.0px;" %)(% style="margin-left: 60.0px;" %)
		99	(((
		100	--station--
		101	)))\|=(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		102	(((
		103	--drive-through track--
		104	)))
		105	(% style="margin-left: 30.0px;" %)\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		106	(((
		107	--IC_station--
		108	)))\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		109	(((
		110	--IC_ST_1--
		111	)))
		112	(% style="margin-left: 30.0px;" %)\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		113	(((
		114	--OC_station--
		115	)))\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		116	(((
		117	--OC_ST_3--
		118	)))
		119	(% style="margin-left: 30.0px;" %)\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		120	(((
		121	--KH_station--
		122	)))\|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
		123	(((
		124	--KH_ST_5--
		125	)))
		126	(% style="margin-left: 30.0px;" %)\|(% colspan="1" style="margin-left: 30.0px;" %)(% colspan="1" style="margin-left: 30.0px;" %)
		127	(((
		128	--KH_station(r)--
		129	)))\|(% colspan="1" style="margin-left: 30.0px;" %)(% colspan="1" style="margin-left: 30.0px;" %)
		130	(((
		131	--KH_ST_1--
		132	)))
		133
		134	* If the preferred station track is blocked the trains can switch to any other free track.
		135	While cleanup is active the trains on IC_ST_1, OC_ST_3 or KH_ST_1 circle until all tracks are done.
		136
		137	== Rulesets ==
		138
		139	=== Logging ===
		140
		141	* All log messages must be prefixed. For Station-2-Station controllers the prefix [trainnum][ST-ST] must be used.
		142	* The variable debug indicates verbose logging.
		143	* Station-2-Station controllers should produce a log message when entering a new train segment even without verbose logging.
		144	* With verbose logging every state can produce a log message as an entry action.
		145	* Function //println(String str)// must be used to produce textual output.
		146	* //printf()// or other IO functions must not be used, because output may not be flushed correctly.
		147
		148	=== Codestyle ===
		149
		150	* Use entry-/exit-actions instead of actions on transitions, if possible.
		151	* If using hostcode, only use functions delivered by our own C-Interface and not the Höhrmann-API.
		152
		153	=== Deadlock Prevention ===
		154
		155	* When attempting to reserve more than one segment (Entering a station, passing a junction) a separate protocol for deadlock prevention must be adhered to.
		156	* In each tick the controller must check if only partial permissions were granted.
		157	* If partial permission was granted the train waits for one tick and releases all locks.
		158	* In the following tick the locks are requested again.
		159	* As a special case the controllers passing through KIO_LN_0 or KIO_LN_1 must wait an additional tick after releasing the requests.
		160	* A sample controller can be found in the repository at [[/doc/deadlocks/resolve_deadlock.sct>>url:https://git.rtsys.informatik.uni-kiel.de/projects/PRAK/repos/14ss-railway/browse/doc/deadlocks/resolve_deadlock.sct\|\|shape="rect"]]