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
-received within a certain time. To receive this timeout you have to set the
-``receiveTimeout`` property and declare handing for the ReceiveTimeout
-message.
+The `UntypedActorContext` :meth:`setReceiveTimeout` defines the inactivity timeout after which
+the sending of a `ReceiveTimeout` message is triggered.
+When specified, the receive function should be able to handle an `akka.actor.ReceiveTimeout` 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