Merge pull request #799 from akka/wip-2612-improve-receivetimeout-docs-√

#2612 - Clarifying ReceiveTimeout semantics in the documentation.

akka-docs/rst/java/code/docs/actor/MyReceivedTimeoutUntypedActor.java

@@ -11,13 +11,18 @@ import scala.concurrent.util.Duration;
 public class MyReceivedTimeoutUntypedActor extends UntypedActor {
 
   public MyReceivedTimeoutUntypedActor() {
+    // To set an initial delay
     getContext().setReceiveTimeout(Duration.parse("30 seconds"));
   }
 
   public void onReceive(Object message) {
     if (message.equals("Hello")) {
+      // To set in a response to a message
+      getContext().setReceiveTimeout(Duration.parse("10 seconds"));
       getSender().tell("Hello world", getSelf());
     } else if (message == ReceiveTimeout.getInstance()) {
+      // To turn it off
+      getContext().setReceiveTimeout(Duration.Undefined());
       throw new RuntimeException("received timeout");
     } else {
       unhandled(message);

akka-docs/rst/java/untyped-actors.rst

@@ -431,13 +431,20 @@ defaults to a 'dead-letter' actor ref.
     getSender().tell(result);       // will have dead-letter actor as default
   }
 
-Initial receive timeout
+Receive timeout
-=======================
+===============
 
-A timeout mechanism can be used to receive a message when no initial message is
+The `UntypedActorContext` :meth:`setReceiveTimeout` defines the inactivity timeout after which
-received within a certain time. To receive this timeout you have to set the
+the sending of a `ReceiveTimeout` message is triggered.
-``receiveTimeout`` property and declare handing for the ReceiveTimeout
+When specified, the receive function should be able to handle an `akka.actor.ReceiveTimeout` message.
-message.
+1 millisecond is the minimum supported timeout.
+
+Please note that the receive timeout might fire and enqueue the `ReceiveTimeout` message right after
+another message was enqueued; hence it is **not guaranteed** that upon reception of the receive
+timeout there must have been an idle period beforehand as configured via this method.
+
+Once set, the receive timeout stays in effect (i.e. continues firing repeatedly after inactivity
+periods). Pass in `Duration.Undefined` to switch off this feature.
 
 .. includecode:: code/docs/actor/MyReceivedTimeoutUntypedActor.java#receive-timeout
 

akka-docs/rst/scala/actors.rst

@@ -549,13 +549,20 @@ defaults to a 'dead-letter' actor ref.
     val result = process(request)
     sender ! result       // will have dead-letter actor as default
 
-Initial receive timeout
+Receive timeout
-=======================
+===============
 
-A timeout mechanism can be used to receive a message when no initial message is
+The `ActorContext` :meth:`setReceiveTimeout` defines the inactivity timeout after which
-received within a certain time. To receive this timeout you have to set the
+the sending of a `ReceiveTimeout` message is triggered.
-``receiveTimeout`` property and declare a case handing the ReceiveTimeout
+When specified, the receive function should be able to handle an `akka.actor.ReceiveTimeout` message.
-object.
+1 millisecond is the minimum supported timeout.
+
+Please note that the receive timeout might fire and enqueue the `ReceiveTimeout` message right after
+another message was enqueued; hence it is **not guaranteed** that upon reception of the receive
+timeout there must have been an idle period beforehand as configured via this method.
+
+Once set, the receive timeout stays in effect (i.e. continues firing repeatedly after inactivity
+periods). Pass in `Duration.Undefined` to switch off this feature.
 
 .. includecode:: code/docs/actor/ActorDocSpec.scala#receive-timeout
 

akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala

@@ -269,11 +269,18 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     //#receive-timeout
     import akka.actor.ReceiveTimeout
     import scala.concurrent.util.duration._
+    import scala.concurrent.util.Duration
     class MyActor extends Actor {
+      // To set an initial delay
       context.setReceiveTimeout(30 milliseconds)
       def receive = {
-        case "Hello"        ⇒ //...
+        case "Hello" ⇒
-        case ReceiveTimeout ⇒ throw new RuntimeException("received timeout")
+          // To set in a response to a message
+          context.setReceiveTimeout(100 milliseconds)
+        case ReceiveTimeout ⇒
+          // To turn it off
+          context.setReceiveTimeout(Duration.Undefined)
+          throw new RuntimeException("Receive timed out")
       }
     }
     //#receive-timeout