From f19d6828989582bc53086ce9d8dc35e52c02dc2a Mon Sep 17 00:00:00 2001 From: Mikko Rasa Date: Wed, 16 Apr 2014 22:02:01 +0300 Subject: [PATCH] Improve comments --- source/libr2c2/trainrouter.cpp | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/source/libr2c2/trainrouter.cpp b/source/libr2c2/trainrouter.cpp index fec9782..ca3e93d 100644 --- a/source/libr2c2/trainrouter.cpp +++ b/source/libr2c2/trainrouter.cpp @@ -91,6 +91,9 @@ void TrainRouter::route_changed() bool already_at_end = false; if(!routes.empty()) { + /* Find the route that should be used for the next allocated block. We + can't rely on the resync code in block_reserved since we may need to + clear the stop marker to continue allocation. */ TrackIter track = train.get_block_allocator().first().track_iter(); for(; track; track=track.next()) { @@ -106,12 +109,15 @@ void TrainRouter::route_changed() if(!already_at_end) { + // We are not at the end of the route now, but might have been before. arrival = ON_THE_WAY; train.stop_at(0); train.refresh_blocks_from(*fncb); } else if(!arrival) { + /* If arrival wasn't set before (perhaps because we weren't on a route), + set it now. */ arrival = RESERVED_TO_END; train.stop_at(&*fncb.flip()); train.refresh_blocks_from(*fncb); @@ -274,13 +280,17 @@ void TrainRouter::block_reserved(Block &block, Train *t) if(!t) return; + // Are we waiting for the other train to pass a sequence point? SequencePoint &sp = sequence_points.front(); if(sp.preceding_train==t && sp.block==&block) + /* The other train's router will advance its sequence on the same + signal and may not have handled it yet. */ sequence_check_pending = true; return; } + // Did we reach our next sequence point? if(!sequence_points.empty()) { SequencePoint &sp = sequence_points.front(); @@ -293,7 +303,7 @@ void TrainRouter::block_reserved(Block &block, Train *t) TrackIter track = train.get_block_allocator().iter_for(block).track_iter(); - // Is the block a turnout? If so, set it to the proper path. + // Is the block a turnout? If it is, set it to the correct path. if(unsigned taddr = block.get_turnout_address()) { int path = (*reserving_route)->get_turnout(taddr); @@ -301,6 +311,8 @@ void TrainRouter::block_reserved(Block &block, Train *t) track->set_active_path(path); } + /* If the allocator has released blocks from the front, we may need to + resync reserving_route. */ if(reserving_route==routes.end() || !(*reserving_route)->has_track(*track)) { reserving_route = routes.begin(); @@ -315,11 +327,13 @@ void TrainRouter::block_reserved(Block &block, Train *t) } } - // Do we need to move to the next route? + /* Keep reserving_route pointing to the route containing the block that is + expected to be allocated next. */ for(; track; track=track.next((*reserving_route)->get_path(*track))) { if(!advance_to_track(reserving_route, *track)) { + // We've reached the end of the route. Stop here. arrival = RESERVED_TO_END; train.stop_at(&block); return; @@ -328,6 +342,7 @@ void TrainRouter::block_reserved(Block &block, Train *t) break; } + // Do we need to wait for another train to pass? if(!sequence_points.empty()) { SequencePoint &sp = sequence_points.front(); @@ -342,6 +357,7 @@ void TrainRouter::train_advanced(Block &block) if(!waypoints.empty()) { + // A waypoint is considered reached when the train has advanced through it. const TrackChain &wp = *waypoints.front(); TrackIter t_iter = b_iter.track_iter(); if(wp.has_track(*t_iter)) @@ -366,7 +382,7 @@ void TrainRouter::train_rear_advanced(Block &block) { Track &track = *train.get_block_allocator().iter_for(block).endpoint().track; - // Have we left some routes completely behind? + // Drop any routes that are now completely behind the train. for(RouteList::iterator i=routes.begin(); i!=routes.end(); ++i) if((*i)->has_track(track)) { -- 2.45.2