Consider modeling scheduled pulses, fixed period pulses, and interval pulses

[kevincianfarini]

Summary

Right now this library only supports scheduled and fixed period pulses. That is -- the beat occurs whether the downstream consumer is ready for it or not. These operations are back pressure sensitive because they are scheduled to occur at a specific moment in time ahead of its occurance. We currently have no way to model interval pulses -- pulses which ensure a set amount of time occurs between pulse beats. We should consider supporting both.

Possible API

We might model this with two separate wrappers around the underlying flow. First, a ScheduledPulse which requires that we pass a RecurringJobMode when beating the pulse. This is what is currently present, though the name is different.

public class ScheduledPulse {
    /**
     * Invoke [action] every time this Pulse is set to execute. [Action][action] provides two [instants][Instant]
     * denoting when the pulse was scheduled to occur, and when it actually occurred.
     *
     * This operator will execute [action] according to which [mode] is specified.
     */
    public suspend fun beat(
        mode: RecurringJobMode = RecurringJobMode.CancellingSequential,
        action: suspend (scheduled: Instant, occurred: Instant) -> Unit,
    ): Unit
}

And a second IntervalPulse which does not require any guidance on what to do when backpressure is applied.

public class IntervalPulse {
    /**
     * Invoke [action] every time this Pulse is set to execute. [Action][action] provides two [instants][Instant]
     * denoting when the pulse was scheduled to occur, and when it actually occurred.
     */
    public suspend fun beat(
        action: suspend (scheduled: Instant, occurred: Instant) -> Unit,
    ): Unit
}

The case for this proposal

Based on the discussion in Kotlin/kotlinx.coroutines#3680 it seems like people want a simple function that allows users to invoke an action on some set interval. Cardiologist doesn't currently support monotonic time intervals, and in the absence of kotlinx-coroutines picking this up, maybe we could provide that functionality.

The case against this proposal

Cardiologist, at its core, is not about monotonic time. One reason the receiver value on the existing functions is Clock is because we need to periodically check to see if we've experienced clock drift and react accordingly. The values Clock.now returns might be in the past, far in the future, or just right.

The reference to the current Instant provides little value to interval pulses and therefore also shouldn't care about clock drift. In comparison, users of this library do care about clock drift, and therefore only ever care about schedules and not intervals.

Do we want to provide monotonic time scheduling capabilities in this library, or only datetime based scheduling? My hunch is we stick only to datetime and document that up front. If anyone has uses for interval based monotonic time scheduling please drop that feedback in the comments.

[kevincianfarini]

After a few weeks, I think it's safe to say that cardiologist cares about datetimes and not monotonic time. I'm going to close this as unplanned, and will consider reopening if someone chimes in with a convincing case.