KSLCore/ksl.modeling.agent/TravelHandle

TravelHandle

class TravelHandle<A : AgentLike>(source)

Mutable handle representing an in-progress interruptible travel in 2D. Returned by startTravel; consumed by awaitTravel. The integration loop inside awaitTravel reads this handle on every step, so external entities (dispatchers, statecharts, other agents) can interrupt or redirect by calling cancel / redirect from their own coroutine context.

Latency note: interruptions are observed at the next step boundary, with maximum latency stepSize / velocity. Tight control loops should use a smaller stepSize at the cost of more events.

See §12.6 of the agent-based-modeling design doc for the motivating use cases (AGV recall, mid-trip rerouting, low-battery divert, danger-signal pedestrian reroute, etc.).

Properties

agent

val agent: A

destination

var destination: Point2D

Current target. May differ from the original after redirect.

distanceTraveled

var distanceTraveled: Double

Cumulative distance the agent has actually moved through the projection since startedAt. Includes the prefixes of any legs that were truncated by redirect or cancel.

endedAt

var endedAt: Double

End time of the travel — set when the integration loop exits (complete or canceled). Double.NaN while still active.

isActive

val isActive: Boolean

True while the travel is in progress (not yet complete or canceled).

isCanceled

var isCanceled: Boolean

True after cancel is called.

isComplete

var isComplete: Boolean

True after a successful arrival at the (possibly redirected) destination.

result

val result: TravelResult

TravelResult snapshot. While active, arrivedAt reflects the current simulated time. After complete / canceled, it reflects the end time.

space

val space: ContinuousProjection<in A>

startedAt

val startedAt: Double

stepSize

val stepSize: Double

velocity

val velocity: Double

Functions

cancel

fun cancel()

Stop motion at the agent's current interpolated position. The integration loop sees isCanceled on its next step check and exits with isComplete = false, isCanceled = true. awaitTravel then returns a TravelResult whose arrivedAt is the cancellation time and distance is the actual distance traveled so far.

redirect

fun redirect(newDestination: Point2D)

Change the destination mid-travel. The integration loop sees the new target on its next step boundary and re-plans the direction from the agent's current position. Cumulative distanceTraveled keeps growing across the redirect.