# Schedule Combinators

Schedules define stateful, possibly effectful, recurring schedules of events, and compose in a variety of ways. Combinators allow us to take schedules and combine them together to get other schedules and if we have combinators with just the right properties. Then in theory we should be able to solve an infinite number of problems, with only a few combinators and few base schedules.

## Composition

Schedules compose in the following primary ways:

**Union**. This performs the union of the intervals of two schedules.**Intersection**. This performs the intersection of the intervals of two schedules.**Sequencing**. This concatenates the intervals of one schedule onto another.

### Union

Combines two schedules through union, by recurring if either schedule wants to recur, using the minimum of the two delays between recurrences.

`s1` | `s2` | `s1` | | `s2` | |
---|---|---|---|

Type | `Schedule[R, A, B]` | `Schedule[R, A, C]` | `Schedule[R, A, (B, C)]` |

Continue: `Boolean` | `b1` | `b2` | `b1` | | `b2` |

Delay: `Duration` | `d1` | `d2` | `d1.min(d2)` |

Emit: `(A, B)` | `a` | `b` | `(a, b)` |

We can combine two schedule through union with `||`

operator:

`val expCapped = Schedule.exponential(100.milliseconds) || Schedule.spaced(1.second)`

### Intersection

Combines two schedules through the intersection, by recurring only if both schedules want to recur, using the maximum of the two delays between recurrences.

`s1` | `s2` | `s1 && s2` | |
---|---|---|---|

Type | `Schedule[R, A, B]` | `Schedule[R, A, C]` | `Schedule[R, A, (B, C)]` |

Continue: `Boolean` | `b1` | `b2` | `b1 && b2` |

Delay: `Duration` | `d1` | `d2` | `d1.max(d2)` |

Emit: `(A, B)` | `a` | `b` | `(a, b)` |

We can intersect two schedule with `&&`

operator:

`val expUpTo10 = Schedule.exponential(1.second) && Schedule.recurs(10)`

### Sequencing

Combines two schedules sequentially, by following the first policy until it ends, and then following the second policy.

`s1` | `s2` | `s1 andThen s2` | |
---|---|---|---|

Type | `Schedule[R, A, B]` | `Schedule[R, A, C]` | `Schedule[R, A, C]` |

Delay: `Duration` | `d1` | `d2` | `d1 + d2` |

Emit: `B` | `a` | `b` | `b` |

We can sequence two schedule by using `andThen`

:

`val sequential = Schedule.recurs(10) andThen Schedule.spaced(1.second)`

## Piping

Combine two schedules by piping the output of the first schedule to the input of the other. Effects described by the first schedule will always be executed before the effects described by the second schedule.

`s1` | `s2` | `s1 >>> s2` | |
---|---|---|---|

Type | `Schedule[R, A, B]` | `Schedule[R, B, C]` | `Schedule[R, A, C]` |

Delay: `Duration` | `d1` | `d2` | `d1 + d2` |

Emit: `B` | `a` | `b` | `b` |

We can pipe two schedule by using `>>>`

operator:

`val totalElapsed = Schedule.spaced(1.second) <* Schedule.recurs(5) >>> Schedule.elapsed`

## Jittering

A `jittered`

is a combinator that takes one schedule and returns another schedule of the same type except for the delay which is applied randomly:

Function | Input Type | Output Type |
---|---|---|

`jittered` | `Schedule[Env with Random, In, Out]` | |

`jittered` | `min: Double, max: Double` | `Schedule[Env with Random, In, Out]` |

We can jitter any schedule by calling `jittered`

on it:

`val jitteredExp = Schedule.exponential(10.milliseconds).jittered`

When a resource is out of service due to overload or contention, retrying and backing off doesn't help us. If all failed API calls are backed off to the same point of time, they cause another overload or contention. Jitter adds some amount of randomness to the delay of the schedule. This helps us to avoid ending up accidentally synchronizing and taking the service down by accident.

The form with parameters `min`

and `max`

creates a new schedule where the new interval size is randomly distributed between `min * old interval`

and `max * old interval`

.

Research shows that `Schedule.jittered(0.0, 1.0)`

is very suitable for retrying.

## Collecting

A `collectAll`

is a combinator that when we call it on a schedule, produces a new schedule that collects the outputs of the first schedule into a chunk.

Function | Input Type | Output Type |
---|---|---|

`collectAll` | `Schedule[Env, In, Out]` | `Schedule[Env, In, Chunk[Out]]` |

In the following example, we are catching all recurrence of schedule into `Chunk`

, so at the end, it would contain `Chunk(0, 1, 2, 3, 4)`

:

`val collect = Schedule.recurs(5).collectAll`

## Filtering

We can filter inputs or outputs of a schedule with `whileInput`

and `whileOutput`

. Alse ZIO schedule has an effectful version of these two functions, `whileInputZIO`

and `whileOutputZIO`

.

Function | Input Type | Output Type |
---|---|---|

`whileInput` | `In1 => Boolean` | `Schedule[Env, In1, Out]` |

`whileOutput` | `Out => Boolean` | `Schedule[Env, In, Out]` |

`whileInputZIO` | `In1 => URIO[Env1, Boolean]` | `Schedule[Env1, In1, Out]` |

`whileOutputZIO` | `Out => URIO[Env1, Boolean]` | `Schedule[Env1, In, Out]` |

In following example we collect all emiting outputs before reaching the 5 output, so it would return `Chunk(0, 1, 2, 3, 4)`

:

`val res = Schedule.unfold(0)(_ + 1).whileOutput(_ < 5).collectAll`

## Mapping

There are two versions for mapping schedules, `map`

and its effectful version `mapZIO`

.

Function | Input Type | Output Type |
---|---|---|

`map` | `f: Out => Out2` | `Schedule[Env, In, Out2]` |

`mapZIO` | `f: Out => URIO[Env1, Out2]` | `Schedule[Env1, In, Out2]` |

## Left/Right Ap

Sometimes when we intersect two schedules with the `&&`

operator, we just need to ignore the left or the right output.

`*>`

ignore the left output

`<*`

ignore the right output

## Modifying

Modifies the delay of a schedule:

`val boosted = Schedule.spaced(1.second).delayed(_ => 100.milliseconds)`

## Tapping

Whenever we need to effectfully process each schedule input/output, we can use `tapInput`

and `tapOutput`

.

We can use these two functions for logging purposes:

`val tappedSchedule = Schedule.count.whileOutput(_ < 5).tapOutput(o => Console.printLine(s"retrying $o").orDie)`