diff --git a/akka-docs/common/index.rst b/akka-docs/common/index.rst index f3ed26aa73..4e19d1a1aa 100644 --- a/akka-docs/common/index.rst +++ b/akka-docs/common/index.rst @@ -4,5 +4,4 @@ Common utilities .. toctree:: :maxdepth: 2 - scheduler duration diff --git a/akka-docs/java/code/akka/docs/actor/UntypedActorTest.scala b/akka-docs/java/code/akka/docs/actor/SchedulerDocTest.scala similarity index 51% rename from akka-docs/java/code/akka/docs/actor/UntypedActorTest.scala rename to akka-docs/java/code/akka/docs/actor/SchedulerDocTest.scala index 1747f30f92..b522a142d8 100644 --- a/akka-docs/java/code/akka/docs/actor/UntypedActorTest.scala +++ b/akka-docs/java/code/akka/docs/actor/SchedulerDocTest.scala @@ -2,4 +2,4 @@ package akka.docs.actor import org.scalatest.junit.JUnitSuite -class UntypedActorTest extends UntypedActorTestBase with JUnitSuite +class SchedulerDocTest extends SchedulerDocTestBase with JUnitSuite diff --git a/akka-docs/java/code/akka/docs/actor/SchedulerDocTestBase.java b/akka-docs/java/code/akka/docs/actor/SchedulerDocTestBase.java new file mode 100644 index 0000000000..bbcec2f4e5 --- /dev/null +++ b/akka-docs/java/code/akka/docs/actor/SchedulerDocTestBase.java @@ -0,0 +1,85 @@ +package akka.docs.actor; + +//#imports1 +import akka.actor.Props; +import akka.util.Duration; +import java.util.concurrent.TimeUnit; + +//#imports1 + +//#imports2 +import akka.actor.UntypedActor; +import akka.actor.UntypedActorFactory; +import akka.actor.Cancellable; + +//#imports2 + +import akka.actor.ActorRef; +import akka.actor.ActorSystem; +import akka.testkit.AkkaSpec; + +import org.junit.After; +import org.junit.Before; +import org.junit.Test; +import static org.junit.Assert.*; + +public class SchedulerDocTestBase { + + ActorSystem system; + ActorRef testActor; + + @Before + public void setUp() { + system = ActorSystem.create("MySystem", AkkaSpec.testConf()); + testActor = system.actorOf(new Props().withCreator(MyUntypedActor.class)); + } + + @After + public void tearDown() { + system.shutdown(); + } + + @Test + public void scheduleOneOffTask() { + //#schedule-one-off-message + //Schedules to send the "foo"-message to the testActor after 50ms + system.scheduler().scheduleOnce(Duration.create(50, TimeUnit.MILLISECONDS), testActor, "foo"); + //#schedule-one-off-message + + //#schedule-one-off-thunk + //Schedules a Runnable to be executed (send the current time) to the testActor after 50ms + system.scheduler().scheduleOnce(Duration.create(50, TimeUnit.MILLISECONDS), new Runnable() { + @Override + public void run() { + testActor.tell(System.currentTimeMillis()); + } + }); + //#schedule-one-off-thunk + } + + @Test + public void scheduleRecurringTask() { + //#schedule-recurring + ActorRef tickActor = system.actorOf(new Props().withCreator(new UntypedActorFactory() { + public UntypedActor create() { + return new UntypedActor() { + public void onReceive(Object message) { + if (message.equals("Tick")) { + // Do someting + } + } + }; + } + })); + + //This will schedule to send the Tick-message + //to the tickActor after 0ms repeating every 50ms + Cancellable cancellable = system.scheduler().schedule(Duration.Zero(), Duration.create(50, TimeUnit.MILLISECONDS), + tickActor, "Tick"); + + //This cancels further Ticks to be sent + cancellable.cancel(); + //#schedule-recurring + system.stop(tickActor); + } +} diff --git a/akka-docs/java/code/akka/docs/actor/UntypedActorDocTest.scala b/akka-docs/java/code/akka/docs/actor/UntypedActorDocTest.scala new file mode 100644 index 0000000000..76b3b990fa --- /dev/null +++ b/akka-docs/java/code/akka/docs/actor/UntypedActorDocTest.scala @@ -0,0 +1,5 @@ +package akka.docs.actor + +import org.scalatest.junit.JUnitSuite + +class UntypedActorDocTest extends UntypedActorDocTestBase with JUnitSuite diff --git a/akka-docs/java/code/akka/docs/actor/UntypedActorTestBase.java b/akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java similarity index 99% rename from akka-docs/java/code/akka/docs/actor/UntypedActorTestBase.java rename to akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java index 3cc234176b..1093f58caf 100644 --- a/akka-docs/java/code/akka/docs/actor/UntypedActorTestBase.java +++ b/akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java @@ -36,7 +36,7 @@ import java.util.concurrent.TimeUnit; import static org.junit.Assert.*; -public class UntypedActorTestBase { +public class UntypedActorDocTestBase { @Test public void systemActorOf() { diff --git a/akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java b/akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java index 2da942fdef..28c0ad4477 100644 --- a/akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java +++ b/akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java @@ -28,7 +28,7 @@ import com.typesafe.config.ConfigFactory; import akka.actor.ActorSystem; import akka.docs.actor.MyUntypedActor; -import akka.docs.actor.UntypedActorTestBase.MyActor; +import akka.docs.actor.UntypedActorDocTestBase.MyActor; import akka.testkit.AkkaSpec; public class DispatcherDocTestBase { diff --git a/akka-docs/java/index.rst b/akka-docs/java/index.rst index e864b9d63c..c04e5bc259 100644 --- a/akka-docs/java/index.rst +++ b/akka-docs/java/index.rst @@ -9,6 +9,7 @@ Java API untyped-actors typed-actors logging + scheduler futures dataflow transactors diff --git a/akka-docs/java/scheduler.rst b/akka-docs/java/scheduler.rst new file mode 100644 index 0000000000..3dde1345a6 --- /dev/null +++ b/akka-docs/java/scheduler.rst @@ -0,0 +1,53 @@ + +.. _scheduler-java: + +################## + Scheduler (Java) +################## + +Sometimes the need for making things happen in the future arises, and where do you go look then? +Look no further than ``ActorSystem``! There you find the :meth:`scheduler` method that returns an instance +of akka.actor.Scheduler, this instance is unique per ActorSystem and is used internally for scheduling things +to happen at specific points in time. Please note that the scheduled tasks are executed by the default +``MessageDispatcher`` of the ``ActorSystem``. + +You can schedule sending of messages to actors and execution of tasks (functions or Runnable). +You will get a ``Cancellable`` back that you can call :meth:`cancel` on to cancel the execution of the +scheduled operation. + +Some examples +------------- + +.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java + :include: imports1,schedule-one-off-message + +.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java + :include: schedule-one-off-thunk + +.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java + :include: imports1,imports2,schedule-recurring + +From ``akka.actor.ActorSystem`` +------------------------------- + +.. includecode:: ../../akka-actor/src/main/scala/akka/actor/ActorSystem.scala + :include: scheduler + + +The Scheduler interface +----------------------- + +.. includecode:: ../../akka-actor/src/main/scala/akka/actor/Scheduler.scala + :include: scheduler + +The Cancellable interface +------------------------- + +This allows you to ``cancel`` something that has been scheduled for execution. + +.. warning:: + This does not abort the execution of the task, if it had already been started. + +.. includecode:: ../../akka-actor/src/main/scala/akka/actor/Scheduler.scala + :include: cancellable + diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst index e1fad292fc..8ad7a7f7b2 100644 --- a/akka-docs/java/untyped-actors.rst +++ b/akka-docs/java/untyped-actors.rst @@ -42,7 +42,7 @@ Here is an example: Creating Actors with default constructor ---------------------------------------- -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: imports,system-actorOf The call to :meth:`actorOf` returns an instance of ``ActorRef``. This is a handle to @@ -85,7 +85,7 @@ which can lead to corrupt data. Here is an example: -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#creating-constructor +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-constructor This way of creating the Actor is also great for integrating with Dependency Injection (DI) frameworks like Guice or Spring. @@ -95,7 +95,7 @@ Creating Actors with Props ``Props`` is a configuration object to specify additional things for the actor to be created, such as the ``MessageDispatcher``. -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#creating-props +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-props UntypedActor API @@ -119,7 +119,7 @@ In addition, it offers: The remaining visible methods are user-overridable life-cycle hooks which are described in the following: -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#lifecycle-callbacks +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#lifecycle-callbacks The implementations shown above are the defaults provided by the :class:`UntypedActor` class. @@ -250,7 +250,7 @@ To complete the future with an exception you need send a Failure message to the This is not done automatically when an actor throws an exception while processing a message. -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#reply-exception +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#reply-exception If the actor does not complete the future, it will expire after the timeout period, specified as parameter to the ``ask`` method. @@ -278,7 +278,7 @@ even if that entails waiting for it (but keep in mind that waiting inside an actor is prone to dead-locks, e.g. if obtaining the result depends on processing another message on this actor). -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: import-future,using-ask Forward message @@ -379,7 +379,7 @@ If the ``PoisonPill`` was sent with ``ask``, the ``Future`` will be completed wi Use it like this: -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: import-actors,poison-pill .. _UntypedActor.HotSwap: @@ -400,7 +400,7 @@ The hotswapped code is kept in a Stack which can be pushed and popped. To hotswap the Actor using ``getContext().become``: -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: import-procedure,hot-swap-actor The ``become`` method is useful for many different things, such as to implement @@ -430,7 +430,7 @@ through regular supervisor semantics. Use it like this: -.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java +.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: import-actors,kill Actors and exceptions diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst index 04b13f3f92..dcb7ed2795 100644 --- a/akka-docs/scala/actors.rst +++ b/akka-docs/scala/actors.rst @@ -40,7 +40,7 @@ along with the implementation of how the messages should be processed. Here is an example: -.. includecode:: code/ActorDocSpec.scala +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala :include: imports1,my-actor Please note that the Akka Actor ``receive`` message loop is exhaustive, which is @@ -53,7 +53,7 @@ thrown and the actor is restarted when an unknown message is received. Creating Actors with default constructor ---------------------------------------- -.. includecode:: code/ActorDocSpec.scala +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala :include: imports2,system-actorOf The call to :meth:`actorOf` returns an instance of ``ActorRef``. This is a handle to @@ -70,7 +70,7 @@ how the supervisor hierarchy is arranged. When using the context the current act will be supervisor of the created child actor. When using the system it will be a top level actor, that is supervised by the system (internal guardian actor). -.. includecode:: code/ActorDocSpec.scala#context-actorOf +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#context-actorOf Actors are automatically started asynchronously when created. When you create the ``Actor`` then it will automatically call the ``preStart`` @@ -92,7 +92,7 @@ a call-by-name block in which you can create the Actor in any way you like. Here is an example: -.. includecode:: code/ActorDocSpec.scala#creating-constructor +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#creating-constructor Creating Actors with Props @@ -101,7 +101,7 @@ Creating Actors with Props ``Props`` is a configuration object to specify additional things for the actor to be created, such as the ``MessageDispatcher``. -.. includecode:: code/ActorDocSpec.scala#creating-props +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#creating-props Creating Actors using anonymous classes @@ -109,7 +109,7 @@ Creating Actors using anonymous classes When spawning actors for specific sub-tasks from within an actor, it may be convenient to include the code to be executed directly in place, using an anonymous class. -.. includecode:: code/ActorDocSpec.scala#anonymous-actor +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#anonymous-actor .. warning:: @@ -145,7 +145,7 @@ In addition, it offers: You can import the members in the :obj:`context` to avoid prefixing access with ``context.`` -.. includecode:: code/ActorDocSpec.scala#import-context +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#import-context The remaining visible methods are user-overridable life-cycle hooks which are described in the following:: @@ -290,7 +290,7 @@ To complete the future with an exception you need send a Failure message to the This is not done automatically when an actor throws an exception while processing a message. -.. includecode:: code/ActorDocSpec.scala#reply-exception +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#reply-exception If the actor does not complete the future, it will expire after the timeout period, which is taken from one of the following locations in order of precedence: @@ -339,7 +339,7 @@ type, it will throw the exception or a :class:`ClassCastException` (if you want to get :obj:`None` in the latter case, use :meth:`Future.asSilently[T]`). In case of a timeout, :obj:`None` is returned. -.. includecode:: code/ActorDocSpec.scala#using-ask +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#using-ask Forward message --------------- @@ -371,7 +371,7 @@ This method should return a ``PartialFunction``, e.g. a ‘match/case’ clause which the message can be matched against the different case clauses using Scala pattern matching. Here is an example: -.. includecode:: code/ActorDocSpec.scala +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala :include: imports1,my-actor @@ -401,7 +401,7 @@ received within a certain time. To receive this timeout you have to set the ``receiveTimeout`` property and declare a case handing the ReceiveTimeout object. -.. includecode:: code/ActorDocSpec.scala#receive-timeout +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#receive-timeout Stopping actors @@ -465,7 +465,7 @@ pushed and popped. To hotswap the Actor behavior using ``become``: -.. includecode:: code/ActorDocSpec.scala#hot-swap-actor +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#hot-swap-actor The ``become`` method is useful for many different things, but a particular nice example of it is in example where it is used to implement a Finite State Machine @@ -475,12 +475,12 @@ example of it is in example where it is used to implement a Finite State Machine Here is another little cute example of ``become`` and ``unbecome`` in action: -.. includecode:: code/ActorDocSpec.scala#swapper +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#swapper Encoding Scala Actors nested receives without accidentally leaking memory ------------------------------------------------------------------------- -See this `Unnested receive example `_. +See this `Unnested receive example `_. Downgrade @@ -556,4 +556,4 @@ A bit advanced but very useful way of defining a base message handler and then extend that, either through inheritance or delegation, is to use ``PartialFunction.orElse`` chaining. -.. includecode:: code/ActorDocSpec.scala#receive-orElse +.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#receive-orElse diff --git a/akka-docs/scala/code/ActorDocSpec.scala b/akka-docs/scala/code/akka/docs/actor/ActorDocSpec.scala similarity index 100% rename from akka-docs/scala/code/ActorDocSpec.scala rename to akka-docs/scala/code/akka/docs/actor/ActorDocSpec.scala diff --git a/akka-docs/common/code/SchedulerDocSpec.scala b/akka-docs/scala/code/akka/docs/actor/SchedulerDocSpec.scala similarity index 72% rename from akka-docs/common/code/SchedulerDocSpec.scala rename to akka-docs/scala/code/akka/docs/actor/SchedulerDocSpec.scala index 5c4635b864..3192c67e06 100644 --- a/akka-docs/common/code/SchedulerDocSpec.scala +++ b/akka-docs/scala/code/akka/docs/actor/SchedulerDocSpec.scala @@ -1,4 +1,4 @@ -package akka.scheduler.actor +package akka.docs.actor //#imports1 import akka.actor.Actor @@ -10,7 +10,6 @@ import akka.util.duration._ import org.scalatest.{ BeforeAndAfterAll, WordSpec } import org.scalatest.matchers.MustMatchers import akka.testkit._ -import akka.util.duration._ class SchedulerDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) { "schedule a one-off task" in { @@ -22,25 +21,12 @@ class SchedulerDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) { expectMsg(1 second, "foo") //#schedule-one-off-thunk - //Schedules to send the "foo"-message to the testActor after 50ms + //Schedules a function to be executed (send the current time) to the testActor after 50ms system.scheduler.scheduleOnce(50 milliseconds) { - testActor ! "foo" + testActor ! System.currentTimeMillis } //#schedule-one-off-thunk - expectMsg(1 second, "foo") - - //#schedule-one-off-runnable - //Schedules to send the "foo"-message to the testActor after 50ms - system.scheduler.scheduleOnce( - 50 milliseconds, - new Runnable { - def run = testActor ! "foo" - }) - - //#schedule-one-off-runnable - - expectMsg(1 second, "foo") } "schedule a recurring task" in { diff --git a/akka-docs/scala/code/UnnestedReceives.scala b/akka-docs/scala/code/akka/docs/actor/UnnestedReceives.scala similarity index 100% rename from akka-docs/scala/code/UnnestedReceives.scala rename to akka-docs/scala/code/akka/docs/actor/UnnestedReceives.scala diff --git a/akka-docs/scala/index.rst b/akka-docs/scala/index.rst index 978d9a47bb..a36fe9513f 100644 --- a/akka-docs/scala/index.rst +++ b/akka-docs/scala/index.rst @@ -9,6 +9,7 @@ Scala API actors typed-actors logging + scheduler futures dataflow agents diff --git a/akka-docs/common/scheduler.rst b/akka-docs/scala/scheduler.rst similarity index 72% rename from akka-docs/common/scheduler.rst rename to akka-docs/scala/scheduler.rst index d05cea60aa..6089630625 100644 --- a/akka-docs/common/scheduler.rst +++ b/akka-docs/scala/scheduler.rst @@ -1,30 +1,31 @@ -Scheduler -========= + +.. _scheduler-scala: + +################### + Scheduler (Scala) +################### Sometimes the need for making things happen in the future arises, and where do you go look then? -Look no further than ``ActorSystem``! There you find the :meth:``scheduler`` method that returns an instance +Look no further than ``ActorSystem``! There you find the :meth:`scheduler` method that returns an instance of akka.actor.Scheduler, this instance is unique per ActorSystem and is used internally for scheduling things to happen at specific points in time. Please note that the scheduled tasks are executed by the default ``MessageDispatcher`` of the ``ActorSystem``. You can schedule sending of messages to actors and execution of tasks (functions or Runnable). -You will get a ``Cancellable`` back that you can call :meth:``cancel`` on to cancel the execution of the +You will get a ``Cancellable`` back that you can call :meth:`cancel` on to cancel the execution of the scheduled operation. Some examples ------------- -.. includecode:: code/SchedulerDocSpec.scala +.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala :include: imports1,schedule-one-off-message -.. includecode:: code/SchedulerDocSpec.scala - :include: imports1,schedule-one-off-thunk +.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala + :include: schedule-one-off-thunk -.. includecode:: code/SchedulerDocSpec.scala - :include: imports1,schedule-one-off-runnable - -.. includecode:: code/SchedulerDocSpec.scala - :include: imports1,schedule-recurring +.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala + :include: schedule-recurring From ``akka.actor.ActorSystem`` -------------------------------