From 57a1a83dd0cd03133032e5d4cb743ad078af6968 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Endre=20S=C3=A1ndor=20Varga?= Date: Mon, 1 Jul 2013 13:30:53 +0200 Subject: [PATCH] = doc: Added warning about closing over in scheduled tasks #3263 --- akka-docs/rst/java/scheduler.rst | 9 +++++++++ akka-docs/rst/scala/scheduler.rst | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/akka-docs/rst/java/scheduler.rst b/akka-docs/rst/java/scheduler.rst index 38050aa2c0..798ae5863b 100644 --- a/akka-docs/rst/java/scheduler.rst +++ b/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 diff --git a/akka-docs/rst/scala/scheduler.rst b/akka-docs/rst/scala/scheduler.rst index 2ecb87a8a9..f184b67257 100644 --- a/akka-docs/rst/scala/scheduler.rst +++ b/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`` -------------------------------