In the real application scenario of data flow, the need of docking with external systems is often met. These external systems may be Actor systems or some other type of systems. Docking with these external systems means that data streams running in another thread can receive events pushed by the external system and respond to changes in behavior.
If an external system needs to control GraphStage, a control function must be built inside the GraphStage in order to contact and change the internal state of GraphStage. External systems can control GraphStage behavior by calling this control function to send information to GraphStage. akka-stream is a multithreaded asynchronous program, so this function can only be an asynchronous callback. akka-stream provides a function getAsyncCallback function that can put a function into another thread and return its callback:
/**
* Obtain a callback object that can be used asynchronously to re-enter the
* current [[GraphStage]] with an asynchronous notification. The [[invoke()]] method of the returned
* [[AsyncCallback]] is safe to be called from other threads and it will in the background thread-safely
* delegate to the passed callback function. I.e. [[invoke()]] will be called by the external world and
* the passed handler will be invoked eventually in a thread-safe way by the execution environment.
*
* This object can be cached and reused within the same [[GraphStageLogic]].
*/
final def getAsyncCallback[T](handler: T ⇒ Unit): AsyncCallback[T] = {
new AsyncCallback[T] {
override def invoke(event: T): Unit =
interpreter.onAsyncInput(GraphStageLogic.this, event, handler.asInstanceOf[Any ⇒ Unit])
}
}
GetAsyncCallback turns a function T=> Unit into an asynchronous operation function and returns its callback via AsyncCallback. Here is a use case for getAsyncCallback:
//external system
object Injector {
var callback: AsyncCallback[String] = null
def inject(m: String) = {
if (callback != null)
callback.invoke(m)
}
}
class InjectControl(injector: Injector.type) extends GraphStage[FlowShape[String,String]] {
val inport = Inlet[String]("input")
val outport = Outlet[String]("output")
val shape = FlowShape.of(inport,outport)
override def createLogic(inheritedAttributes: Attributes): GraphStageLogic =
new GraphStageLogic(shape) {
var extMessage = ""
override def preStart(): Unit = {
val callback = getAsyncCallback[String] { m =>
if (m.length > 0)
m match {
case "Stop" => completeStage()
case s: String => extMessage = s
}
}
injector.callback = callback
}
setHandler(inport, new InHandler {
override def onPush(): Unit =
if (extMessage.length > 0) {
push(outport,extMessage)
extMessage=""
}
else
push(outport, grab(inport))
})
setHandler(outport, new OutHandler {
override def onPull(): Unit = pull(inport)
})
}
}
The object Injector in the example above simulates an external system. We rewrite the preStart() function in GraphStage InjectControl.createLogic, where we register a callback of String=> Unit function in Injector. This callback function can accept the incoming String and update the internal state extMessage, or terminate the data flow when the String == "Stop" is passed in. In onPush(), extMessage is eventually inserted into the data stream as a stream element. Let's build the test runner for GraphStage:
object InteractWithStreams extends App {
implicit val sys = ActorSystem("demoSys")
implicit val ec = sys.dispatcher
implicit val mat = ActorMaterializer(
ActorMaterializerSettings(sys)
.withInputBuffer(initialSize = 16, maxSize = 16)
)
val source = Source(Stream.from(1)).map(_.toString).delay(1.second,DelayOverflowStrategy.backpressure)
val graph = new InjectControl(Injector)
val flow = Flow.fromGraph(graph)
source.via(flow).to(Sink.foreach(println)).run()
Thread.sleep(2000)
Injector.inject("hello")
Thread.sleep(2000)
Injector.inject("world!")
Thread.sleep(2000)
Injector.inject("Stop")
scala.io.StdIn.readLine()
sys.terminate()
}
The results of trial operation show that:
1
2
hello
4
5
6
world!
8
9
10
Process finished with exit code 0
Correctly insert "hello world!" into a running data stream and terminate it at last.
In addition, a GraphStage can also be used as an Actor to communicate with the outside world. We can build a function (ActorRef, Any) => Unit style inside GraphStage, and then use getStageActor(func).ref to return this function in an ActorRef form:
/**
* Initialize a [[StageActorRef]] which can be used to interact with from the outside world "as-if" an [[Actor]].
* The messages are looped through the [[getAsyncCallback]] mechanism of [[GraphStage]] so they are safe to modify
* internal state of this stage.
*
* This method must (the earliest) be called after the [[GraphStageLogic]] constructor has finished running,
* for example from the [[preStart]] callback the graph stage logic provides.
*
* Created [[StageActorRef]] to get messages and watch other actors in synchronous way.
*
* The [[StageActorRef]]'s lifecycle is bound to the Stage, in other words when the Stage is finished,
* the Actor will be terminated as well. The entity backing the [[StageActorRef]] is not a real Actor,
* but the [[GraphStageLogic]] itself, therefore it does not react to [[PoisonPill]].
*
* @param receive callback that will be called upon receiving of a message by this special Actor
* @return minimal actor with watch method
*/
// FIXME: I don't like the Pair allocation :(
@ApiMayChange
final protected def getStageActor(receive: ((ActorRef, Any)) ⇒ Unit): StageActor = {
_stageActor match {
case null ⇒
val actorMaterializer = ActorMaterializerHelper.downcast(interpreter.materializer)
_stageActor = new StageActor(actorMaterializer, getAsyncCallback, receive)
_stageActor
case existing ⇒
existing.become(receive)
existing
}
}
...
/**
* The ActorRef by which this StageActor can be contacted from the outside.
* This is a full-fledged ActorRef that supports watching and being watched
* as well as location transparent (remote) communication.
*/
def ref: ActorRef = functionRef
Here's an example of the implementation of receive:((ActorRef, Any)=> Unit:
def behavior(m:(ActorRef,Any)): Unit = {
val (sender, msg) = m
msg.asInstanceOf[String] match {
case "Stop" => completeStage()
case s@ _ => extMessage = s
}
}
The input parameter (sender,msg) of this function represents the Actor sending the message and the message sent. As in the previous example, as an internal function of GraphStage, it can use and update the internal state of GraphStage. GraphStage is implemented as follows:
class StageAsActor(extActor: ActorRef) extends GraphStage[FlowShape[String,String]] {
val inport = Inlet[String]("input")
val outport = Outlet[String]("output")
val shape = FlowShape.of(inport,outport)
override def createLogic(inheritedAttributes: Attributes): GraphStageLogic =
new GraphStageLogic(shape) {
var extMessage = ""
override def preStart(): Unit = {
extActor ! getStageActor(behavior).ref
}
def behavior(m:(ActorRef,Any)): Unit = {
val (sender, msg) = m
msg.asInstanceOf[String] match {
case "Stop" => completeStage()
case s@ _ => extMessage = s
}
}
setHandler(inport, new InHandler {
override def onPush(): Unit =
if (extMessage.length > 0) {
push(outport,extMessage)
extMessage=""
}
else
push(outport, grab(inport))
})
setHandler(outport, new OutHandler {
override def onPull(): Unit = pull(inport)
})
}
}
The parameter extActor is the external control Actor. In creatLogic.preStart(), we first pass StageActor to extActor. External systems can control data popularity through extActor:
class Messenger extends Actor with ActorLogging {
var stageActor: ActorRef = _
override def receive: Receive = {
case r: ActorRef =>
stageActor = r
log.info("received stage actorRef")
case s: String => stageActor forward s
log.info(s"forwarding message:$s")
}
}
object GetStageActorDemo extends App {
implicit val sys = ActorSystem("demoSys")
implicit val ec = sys.dispatcher
implicit val mat = ActorMaterializer(
ActorMaterializerSettings(sys)
.withInputBuffer(initialSize = 16, maxSize = 16)
)
val stageActorMessenger = sys.actorOf(Props[Messenger],"forwarder")
val source = Source(Stream.from(1)).map(_.toString).delay(1.second,DelayOverflowStrategy.backpressure)
val graph = new StageAsActor(stageActorMessenger)
val flow = Flow.fromGraph(graph)
source.via(flow).to(Sink.foreach(println)).run()
Thread.sleep(2000)
stageActorMessenger ! "Hello"
Thread.sleep(1000)
stageActorMessenger ! "World!"
Thread.sleep(2000)
stageActorMessenger ! "Stop"
scala.io.StdIn.readLine()
sys.terminate()
}
Messenger is a quintessential intermediary that forwards control messages through StageActor to running data streams.
The following is the source code for this demonstration:
GetAsyncCallBack.scala
import akka.actor._
import akka.stream._
import akka.stream.scaladsl._
import akka.stream.stage._
import scala.concurrent.duration._
//external system
object Injector {
var callback: AsyncCallback[String] = null
def inject(m: String) = {
if (callback != null)
callback.invoke(m)
}
}
class InjectControl(injector: Injector.type) extends GraphStage[FlowShape[String,String]] {
val inport = Inlet[String]("input")
val outport = Outlet[String]("output")
val shape = FlowShape.of(inport,outport)
override def createLogic(inheritedAttributes: Attributes): GraphStageLogic =
new GraphStageLogic(shape) {
var extMessage = ""
override def preStart(): Unit = {
val callback = getAsyncCallback[String] { m =>
if (m.length > 0)
m match {
case "Stop" => completeStage()
case s: String => extMessage = s
}
}
injector.callback = callback
}
setHandler(inport, new InHandler {
override def onPush(): Unit =
if (extMessage.length > 0) {
push(outport,extMessage)
extMessage=""
}
else
push(outport, grab(inport))
})
setHandler(outport, new OutHandler {
override def onPull(): Unit = pull(inport)
})
}
}
object GetAsyncCallbackDemo extends App {
implicit val sys = ActorSystem("demoSys")
implicit val ec = sys.dispatcher
implicit val mat = ActorMaterializer(
ActorMaterializerSettings(sys)
.withInputBuffer(initialSize = 16, maxSize = 16)
)
val source = Source(Stream.from(1)).map(_.toString).delay(1.second,DelayOverflowStrategy.backpressure)
val graph = new InjectControl(Injector)
val flow = Flow.fromGraph(graph)
source.via(flow).to(Sink.foreach(println)).run()
Thread.sleep(2000)
Injector.inject("hello")
Thread.sleep(2000)
Injector.inject("world!")
Thread.sleep(2000)
Injector.inject("Stop")
scala.io.StdIn.readLine()
sys.terminate()
}
GetStageActorDemo.scala
import akka.actor._
import akka.stream._
import akka.stream.scaladsl._
import akka.stream.stage._
import scala.concurrent.duration._
class StageAsActor(extActor: ActorRef) extends GraphStage[FlowShape[String,String]] {
val inport = Inlet[String]("input")
val outport = Outlet[String]("output")
val shape = FlowShape.of(inport,outport)
override def createLogic(inheritedAttributes: Attributes): GraphStageLogic =
new GraphStageLogic(shape) {
var extMessage = ""
override def preStart(): Unit = {
extActor ! getStageActor(behavior).ref
}
def behavior(m:(ActorRef,Any)): Unit = {
val (sender, msg) = m
msg.asInstanceOf[String] match {
case "Stop" => completeStage()
case s@ _ => extMessage = s
}
}
setHandler(inport, new InHandler {
override def onPush(): Unit =
if (extMessage.length > 0) {
push(outport,extMessage)
extMessage=""
}
else
push(outport, grab(inport))
})
setHandler(outport, new OutHandler {
override def onPull(): Unit = pull(inport)
})
}
}
class Messenger extends Actor with ActorLogging {
var stageActor: ActorRef = _
override def receive: Receive = {
case r: ActorRef =>
stageActor = r
log.info("received stage actorRef")
case s: String => stageActor forward s
log.info(s"forwarding message:$s")
}
}
object GetStageActorDemo extends App {
implicit val sys = ActorSystem("demoSys")
implicit val ec = sys.dispatcher
implicit val mat = ActorMaterializer(
ActorMaterializerSettings(sys)
.withInputBuffer(initialSize = 16, maxSize = 16)
)
val stageActorMessenger = sys.actorOf(Props[Messenger],"forwarder")
val source = Source(Stream.from(1)).map(_.toString).delay(1.second,DelayOverflowStrategy.backpressure)
val graph = new StageAsActor(stageActorMessenger)
val flow = Flow.fromGraph(graph)
source.via(flow).to(Sink.foreach(println)).run()
Thread.sleep(2000)
stageActorMessenger ! "Hello"
Thread.sleep(1000)
stageActorMessenger ! "World!"
Thread.sleep(2000)
stageActorMessenger ! "Stop"
scala.io.StdIn.readLine()
sys.terminate()
}