= doc: Added warning about closing over in scheduled tasks #3263

akka-docs/rst/java/scheduler.rst

@@ -39,6 +39,15 @@ Schedule a Runnable, that sends the current time to the testActor, to be execute
 .. includecode:: code/docs/actor/SchedulerDocTest.java
    :include: schedule-one-off-thunk
 
+.. warning::
+
+    If you schedule Runnable instances you should be extra careful
+    to not pass or close over unstable references. In practice this means that you should
+    not call methods on the enclosing Actor from within the Runnable.
+    If you need to schedule an invocation it is better to use the ``schedule()``
+    variant accepting a message and an ``ActorRef`` to schedule a message to self
+    (containing the necessary parameters) and then call the method when the message is received.
+
 Schedule to send the "Tick"-message to the ``tickActor`` after 0ms repeating every 50ms:
 
 .. includecode:: code/docs/actor/SchedulerDocTest.java

akka-docs/rst/scala/scheduler.rst

@@ -35,6 +35,15 @@ Some examples
 .. includecode:: code/docs/actor/SchedulerDocSpec.scala
    :include: schedule-recurring
 
+.. warning::
+
+    If you schedule functions or Runnable instances you should be extra careful
+    to not close over unstable references. In practice this means not using ``this``
+    inside the closure in the scope of an Actor instance, not accessing ``sender`` directly
+    and not calling the methods of the Actor instance directly. If you need to
+    schedule an invocation schedule a message to ``self`` instead (containing the
+    necessary parameters) and then call the method when the message is received.
+
 From ``akka.actor.ActorSystem``
 -------------------------------