/*========== state of the layout ==========*/
+typedef struct MovPosChange MovPosChange;
+
typedef struct {
int step;
long speed;
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 */
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;
};
* 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 ==========*/