scheduleWithFixedDelay vs scheduleAtFixedRate, #26910

* previous `schedule` method is trying to maintain a fixed average frequency
  over time, but that can result in undesired bursts of scheduled tasks after a long
  GC or if the JVM process has been suspended, same with all other periodic
  scheduled message sending via various Timer APIs
* most of the time "fixed delay" is more desirable
* we can't just change because it's too big behavioral change and some might
  depend on previous behavior
* deprecate the old `schedule` and introduce new `scheduleWithFixedDelay`
  and `scheduleAtFixedRate`, when fixing the deprecation warning users should
  make a concious decision of which behavior to use (scheduleWithFixedDelay in
  most cases)

* Streams
* SchedulerSpec
  * test both fixed delay and fixed rate
* TimerSpec
* FSM and PersistentFSM
* mima
* runnable as second parameter list, also in typed.Scheduler
* IllegalStateException vs SchedulerException
* deprecated annotations
* api and reference docs, all places
* migration guide

akka-docs/src/test/java/jdocs/actor/fsm/FSMDocTest.java

@@ -79,7 +79,10 @@ public class FSMDocTest extends AbstractJavaTest {
 
       // #transition-syntax
       onTransition(
-          matchState(Idle, Active, () -> setTimer("timeout", Tick, Duration.ofSeconds(1L), true))
+          matchState(
+                  Idle,
+                  Active,
+                  () -> startTimerWithFixedDelay("timeout", Tick, Duration.ofSeconds(1L)))
               .state(Active, null, () -> cancelTimer("timeout"))
               .state(null, Idle, (f, t) -> log().info("entering Idle from " + f)));
       // #transition-syntax