raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

DOC: Improved scheduler doc. Split into Java/Scala samples

Browse source
This commit is contained in:
Patrik Nordwall 2011-12-14 21:52:39 +01:00
parent c57b2732e7
commit fabe475f64
15 changed files with 188 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

1
akka-docs/common/index.rst
View file

@ -4,5 +4,4 @@ Common utilities
.. toctree::
:maxdepth: 2
scheduler
duration

2
akka-docs/java/code/akka/docs/actor/UntypedActorTest.scala → akka-docs/java/code/akka/docs/actor/SchedulerDocTest.scala
View file

@ -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

85
akka-docs/java/code/akka/docs/actor/SchedulerDocTestBase.java Normal file
View file

@ -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);
}
}

5
akka-docs/java/code/akka/docs/actor/UntypedActorDocTest.scala Normal file
View file

@ -0,0 +1,5 @@
package akka.docs.actor
import org.scalatest.junit.JUnitSuite
class UntypedActorDocTest extends UntypedActorDocTestBase with JUnitSuite

2
akka-docs/java/code/akka/docs/actor/UntypedActorTestBase.java → akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java
View file

@ -36,7 +36,7 @@ import java.util.concurrent.TimeUnit;
import static org.junit.Assert.*;
public class UntypedActorTestBase {
public class UntypedActorDocTestBase {
@Test
public void systemActorOf() {

2
akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java
View file

@ -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 {

1
akka-docs/java/index.rst
View file

@ -9,6 +9,7 @@ Java API
untyped-actors
typed-actors
logging
scheduler
futures
dataflow
transactors

53
akka-docs/java/scheduler.rst Normal file
View file

@ -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

18
akka-docs/java/untyped-actors.rst
View file

@ -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

30
akka-docs/scala/actors.rst
View file

@ -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 <http://github.com/jboner/akka/blob/master/akka/akka-docs/scala/code/UnnestedReceives.scala>`_.
See this `Unnested receive example <http://github.com/jboner/akka/blob/master/akka/akka-docs/scala/code/akka/docs/actor/UnnestedReceives.scala>`_.
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

0
akka-docs/scala/code/ActorDocSpec.scala → akka-docs/scala/code/akka/docs/actor/ActorDocSpec.scala
View file

20
akka-docs/common/code/SchedulerDocSpec.scala → akka-docs/scala/code/akka/docs/actor/SchedulerDocSpec.scala
View file

@ -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 {

0
akka-docs/scala/code/UnnestedReceives.scala → akka-docs/scala/code/akka/docs/actor/UnnestedReceives.scala
View file

1
akka-docs/scala/index.rst
View file

@ -9,6 +9,7 @@ Scala API
actors
typed-actors
logging
scheduler
futures
dataflow
agents

25
akka-docs/common/scheduler.rst → akka-docs/scala/scheduler.rst
View file

@ -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``
-------------------------------