/**
* Sends a request message to an actor, awaits a response value (but no longer than the given
* timeout) and returns it. This method can be called by any code, even non-actor code. If the
* actor responds with an error message, a {@link RuntimeException} will be thrown by this method.
* <br>
* The message's {@code id} and {@code from} properties may be left unset.
*
* <p>This method should be used as in the following example (assuming a {@code String} return
* value:
*
* <pre>{@code
* String res = call(actor, new MyRequest());
* }</pre>
*
* In the example, {@code MyRequest} extends {@link RequestMessage}. Note how the result of the
* {@link #from() from} method is passed to the request's constructor, but the message ID isn't.
*
* @param <V> the return value's type
* @param actor the actor to which the request is sent
* @param timeout the method will not block for longer than the amount remaining in the {@link
* Timeout}
* @return the value sent by the actor as a response
* @throws RuntimeException if the actor responds with an error message, its contained exception
* will be thrown, possibly wrapped by a {@link RuntimeException}.
* @throws TimeoutException if the timeout expires before a response is received from the actor.
* @throws InterruptedException
*/
public static <V> V call(final ActorRef actor, RequestMessage<V> m, Timeout timeout)
throws TimeoutException, InterruptedException, SuspendExecution {
return call(actor, m, timeout.nanosLeft(), TimeUnit.NANOSECONDS);
}
@Override
public boolean send(Message msg, Timeout timeout)
throws SuspendExecution, InterruptedException {
return send(msg, timeout.nanosLeft(), TimeUnit.NANOSECONDS);
}
/**
* Performs a selective receive based on type. This method blocks (but for no longer than the
* given timeout) until a message of the given type is available in the mailbox, and returns it.
* If the given timeout expires, this method returns {@code null}.
*
* <p>Messages that are not selected, are temporarily skipped. They will remain in the mailbox
* until another call to receive (selective or non-selective) retrieves them.
*
* @param <T> The type of the returned value
* @param timeout the method will not block for longer than the amount remaining in the {@link
* Timeout}
* @param type the type of the messages to select
* @return The next message of the wanted type, or {@code null} if the timeout expires.
* @throws SuspendExecution
* @throws InterruptedException
*/
public final <M extends Message> M receive(Timeout timeout, final Class<M> type)
throws SuspendExecution, InterruptedException, TimeoutException {
return receive(timeout.nanosLeft(), TimeUnit.NANOSECONDS, type);
}
/**
* Performs a selective receive. This method blocks (but for no longer than the given timeout)
* until a message that is {@link MessageProcessor#process(java.lang.Object) selected} by the
* given {@link MessageProcessor} is available in the mailbox, and returns the value returned by
* {@link MessageProcessor#process(java.lang.Object) MessageProcessor.process}. If the given
* timeout expires, this method returns {@code null}.
*
* <p>Messages that are not selected, are temporarily skipped. They will remain in the mailbox
* until another call to receive (selective or non-selective) retrieves them.
*
* @param <T> The type of the returned value
* @param timeout the method will not block for longer than the amount remaining in the {@link
* Timeout}
* @param proc performs the selection.
* @return The non-null value returned by {@link MessageProcessor#process(java.lang.Object)
* MessageProcessor.process}, or {@code null} if the timeout expired.
* @throws InterruptedException
*/
public final <T> T receive(Timeout timeout, MessageProcessor<? super Message, T> proc)
throws TimeoutException, SuspendExecution, InterruptedException {
return receive(timeout.nanosLeft(), TimeUnit.NANOSECONDS, proc);
}
@Override
public final boolean send(WebDataMessage message, Timeout timeout)
throws SuspendExecution, InterruptedException {
return send(message, timeout.nanosLeft(), TimeUnit.NANOSECONDS);
}
/**
* Blocks the current strand (either fiber or thread) until the given future completes - but no
* longer than the given timeout - and returns its result.
*
* @param future the future
* @param timeout the method will not block for longer than the amount remaining in the {@link
* Timeout}
* @return the future's result
* @throws ExecutionException if the future's computation threw an exception
* @throws TimeoutException if the timeout expired before the future completed
* @throws InterruptedException if the current thread was interrupted while waiting
*/
public static <V> V get(CompletableFuture<V> future, Timeout timeout)
throws ExecutionException, InterruptedException, SuspendExecution, TimeoutException {
return get(future, timeout.nanosLeft(), TimeUnit.NANOSECONDS);
}
@Override
public Message receive(Timeout timeout) throws SuspendExecution, InterruptedException {
return receiveInternal(timeout.nanosLeft(), TimeUnit.NANOSECONDS);
}
