Requester
Related Doc:
package requester
Hook to add the request() methods to a third-party Actor.
Hook to add the request() methods to a third-party Actor.
Similar to RequestableActorRef, but works with an ActorSelection.
Similar to RequestableActorRef, but works with an ActorSelection.
The response from request() will be wrapped up in here and looped around.
The response from request() will be wrapped up in here and looped around. You shouldn't need to use this directly.
Send a request, and specify the handler for the received response.
Send a request, and specify the handler for the received response. You may also specify a failHandler, which will be run if the operation fails for some reason. (Most often, because we didn't receive a response within the timeout window.)
Normally you don't need to invoke this manually -- Requester defines an unhandled() override that deals with these responses.
Normally you don't need to invoke this manually -- Requester defines an unhandled() override that deals with these responses. But if your receive method intercepts *all* messages for some reason (for example, it stashes everything), then you should add this at the front of your receive so that it deals with responses.
Convert a Future into a Request.
Convert a Future into a Request.
This takes the specified Future, and runs it in the Requester's main loop, to make it properly safe. As usual, sender will be preserved.
This is implicit, so if you are in a context that already expects a Request (such as a for comprehension with a Request at the top), it will quietly turn the Future into a Request. If Request isn't already expected, though, you'll have to specify loopback explicitly.
Convert a Request into a Future.
Convert a Request into a Future.
Sometimes, at the edges of the API, you need to think in terms of Futures. When this is necessary, this implicit will take your RequestM and turn it into a Future of the matching type.
Override this to specify the timeout for requests
Override this to specify the timeout for requests
TODO: this is suspicious, since it does not follow Akka's preferred pattern for timeouts. We might change how this works.
The actual Requester that is going to send the requests and process the responses.
The actual Requester that is going to send the requests and process the responses. If you mix RequesterImplicits into a non-Requester, this must point to that Actor, which does all the real work. (If you are using this from within Requester, it's already set.)
Easy and relatively safe variant of "ask".
The idea here is that it would be lovely to have a replacement for the "ask" pattern. Ask is powerful, but quite dangerous -- in particular, handling the response in the most obvious way, using the Future's completion callbacks, is a fine way to break your Actor's threading and cause strange timing bugs.
So the idea here is to build something with similar semantics to ask, but deliberately a bit dumbed-down and safer for routine use. Where ask returns a Future that you can then put callbacks on, request() takes those callbacks as parameters, and runs them *in this Actor's main thread*.
In other words, I want to be able to say something like:
def receive = { ... case MyMessage(a, b) => { otherActor.request(MyRequest(b)).foreach { case OtherResponse(c) => ... } } }
While OtherResponse is lexically part of MyRequest, it actually *runs* during receive, just like any other incoming message, so it isn't prone to the threading problems that ask is.
How does this work? Under the hood, it actually does use ask, but in a very specific and constrained way. We send the message off using ask, and then hook the resulting Future. When the Future completes, we wrap the response and the handler together in a RequestedResponse message, and loop that back around as a message to the local Actor.
Note that the original sender is preserved, so the callback can use it without problems. (This is the most common error made when using ask, and was one of the motivations for creating Requester.)
Note that, to make this work, the Request trait mixes in its own version of unhandled(). For this to work properly, therefore, it is very important that, if your own Actor overrides unhandled, it calls super.unhandled() for unknown messages!
That unhandled() override is usually enough to catch the looped-back messages, so you usually just need to mix Requester into your Actor. However, if your Actor's receive function is intercepting *all* messages (so nothing makes it to unhandled), then you will need to call handleRequestResponse at the beginning of your receive; otherwise, your Actor can wind up deadlocked. This can particularly happen when using stash() during Actor startup:
In this startup pattern, we are stashing all messages until the persister responds with the Actor's state. However, if we didn't have handleRequestResponse there, the response would also get stashed, so the Actor would never receive the state message, and the Actor would be stuck.
IMPORTANT: Requester is *not* compatible with stateful versions of become() -- that is, if you are using become() in a method where you are capturing the parameters in the closure of become(), Requester will probably not work right. This is because the body of the response handler will capture the closed-over parameter, and if the Actor has become() something else in the meantime, the handler will use the *old* data, not the new.
More generally, Requester should be used with caution if your Actor changes state frequently. While it *can* theoretically be used with FSM, it may not be wise to do so, since the state machine may no longer be in a compatible state by the time the response is received. Requester is mainly intended for Actors that spend most or all of their time in a single state; it generally works quite well for those.