Support for Actor timers, and fix bug in FSM, #15733

* backport of the timers from Akka Typed, #16742
* also fixed a small bug in FSM timers, which could result in that
  a timer from a previous incarnation was let through to new
  incarnation after restart
* no more need for the complicated "how to" section in docs of
  how to schedule periodic messages

akka-docs/src/test/scala/docs/actor/TimerDocSpec.scala

@@ -0,0 +1,33 @@
+/**
+ * Copyright (C) 2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.actor
+
+import akka.actor.Actor
+import scala.concurrent.duration._
+
+object TimerDocSpec {
+  //#timers
+  import akka.actor.Timers
+
+  object MyActor {
+    private case object TickKey
+    private case object FirstTick
+    private case object Tick
+    private case object LaterTick
+  }
+
+  class MyActor extends Actor with Timers {
+    import MyActor._
+    timers.startSingleTimer(TickKey, FirstTick, 500.millis)
+
+    def receive = {
+      case FirstTick =>
+        // do something useful here
+        timers.startPeriodicTimer(TickKey, Tick, 1.second)
+      case Tick =>
+      // do something useful here
+    }
+  }
+  //#timers
+}