From: ian <ian>
Date: Sun, 6 Apr 2008 11:16:51 +0000 (+0000)
Subject: before completely abandon on_done
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ijackson/git?a=commitdiff_plain;h=81e450b79c35840ccc395186fdded2e471672d19;p=trains.git

before completely abandon on_done
---

diff --git a/hostside/safety.h b/hostside/safety.h
index 65faf2d..ec9be10 100644
--- a/hostside/safety.h
+++ b/hostside/safety.h
@@ -30,6 +30,8 @@ typedef short TimeInterval; /*ms*/
 
 /*========== state of the layout ==========*/
 
+typedef struct MovPosChange MovPosChange;
+
 typedef struct {
   int step;
   long speed;
@@ -73,7 +75,6 @@ struct Segment {
   unsigned
     tr_backwards:1, /* train's motion is (would be) backwards wrt track */
     ho_backwards:1, /* home train has its front and rear backwards wrt track */
-    points_moving:1, /* feature(s) have been told to change to movposcomb */
     cm_autostop:1, /* train should stop on detection */
     seg_inverted:1, /* polarity is inverted */
     tr_updated:1, /* for use by safety.c:lay_train etc.; otherwise 0 */
@@ -81,6 +82,7 @@ struct Segment {
   TimeInterval until_here, /* ) nonnegative; */  /* ) always valid but      */
     until_detect;          /* ) 0 if already */  /* )  meaningful iff owner */
   MovPosComb movposcomb;
+  MovPosChange *moving; /* non-0 iff feature(s) have been told to change */
   const SegmentInfo *i;
 };
 
@@ -135,36 +137,52 @@ void safety_notify_detection(Segment *seg);
  * Only safety.c should request changes.
  */
 
-typedef struct MovPosChangeDetails *MovPosChangeRequest;
-typedef void MovPosCallback(Segment*, MovPosChangeRequest, void *u);
-
 ErrorCode
-movpos_requestchange(Segment *back, Segment *move, Segment *fwd,
-		     int maxdelay_ms, MovPosChangeRequest *req_io,
-		     MovPosCallback *on_moving, MovPosCallback *on_done,
-		     void *u);
+movpos_change(Segment *back, Segment *tomove, Segment *fwd,
+	      int maxdelay_ms, MovPosChange *reservation);
   /* back and fwd may be 0 if we don't care (and must be if there is
    * no track in that direction.  It is immaterial which is back and
-   * which fwd.  *req_io should be 0 on entry, or the results of
-   * movpos_reservechange; on successful exit it is non-0.  req_io may
-   * be 0.  Updates seg->movposcomb and seg->points_moving.  Returns
-   * EC_Invalid if there is no movposcomb of move matching back/fwd,
-   * or EC_MovPos if the maxdelay_ms could not be met; on error any
-   * reservation is destroyed and *req_io is undefined. */
-
-void movpos_cancelchange(MovPosChangeRequest /* 0 OK */);
-  /* Cancels any movements not yet done; may leave movposcomb in an
-   * unknown or invalid physical state.  For a reservation, just
-   * discards it without doing anything. */
+   * which fwd.
+   *
+   * If segment has already been requested to change, an attempt is
+   * made to replace that change with the new request; if this is not
+   * successful then the existing change will still happen.
+
+
+   If the
+   * new change can be done, then the old change's callback is
+   * forgotten and we only call the new change's when that's done.
+
+
+   *
+   * reservation should be 0, or the results of movpos_reservechange
+   * on the same move.  It is always consumed, even on error.
+   *
+   * On successful exit, tomove->moving is set non-0; from then on
+   * until ->moving becomes 0, movposcomb may not reflect the real
+   * physical state of the layout; instead it gives only information
+   * about the target configuration.  (Choreographers are allowed to
+   * know implementation details and may know what movposcomb means
+   * for certain segments depending on the movement requested.)
+   *
+   * Returns EC_Invalid if there is no movposcomb of tomove matching
+   * back/fwd, or EC_MovFeatTooLate if the maxdelay_ms could not be
+   * met because of lack of ability to change points.
+   */
+
+ErrorCode
+movpos_reserve(Segment *move, int maxdelay_ms, MovPosChange *res_r);
+  /* Returns EC_MovFeatTooLate if the maxdelay_ms could not be met.
+   * The resulting MovPosChange is a reservation which is guaranteed
+   * to be useable successfully later for any movpos_change for
+   * the same move and a greater or equal maxdelay_ms.  On successful
+   * exit *res_r is set to non-0.  On transition out of Sta_Run,
+   * all unconfirmed reservations must be unreserved before
+   * points_all_abandon is called (see startup.c);
+   */
 
 ErrorCode
-movpos_reservechange(Segment *move, int maxdelay_ms,
-		     MovPosChangeRequest *res_r);
-  /* Returns EC_Points if the maxdelay_ms could not be met.  The resulting
-   * MovPosChangeRequest is a reservation which is guaranteed to be
-   * useable successfully later for any movpos_requestchange for the
-   * same move and a greater or equal maxdelay_ms.  On successful
-   * exit *res_r is set to non-0. */
+movpos_unreserve(Segment *move, MovPosChange *reservation);
 
 /*========== speedmgr.c ==========*/