Integration

mapAsync + ask

A nice way to delegate some processing of elements in a stream to an actor is to use ask in mapAsync. The back-pressure of the stream is maintained by the CompletionStage of the ask and the mailbox of the actor will not be filled with more messages than the given parallelism of the mapAsync stage.

Source<String, NotUsed> words =
  Source.from(Arrays.asList("hello", "hi"));
Timeout askTimeout = Timeout.apply(5, TimeUnit.SECONDS);

words
  .mapAsync(5, elem -> ask(ref, elem, askTimeout))
  .map(elem -> (String) elem)
  // continue processing of the replies from the actor
  .map(elem -> elem.toLowerCase())
  .runWith(Sink.ignore(), mat);

Note that the messages received in the actor will be in the same order as the stream elements, i.e. the parallelism does not change the ordering of the messages. There is a performance advantage of using parallelism > 1 even though the actor will only process one message at a time because then there is already a message in the mailbox when the actor has completed previous message.

The actor must reply to the getSender() for each message from the stream. That reply will complete the CompletionStage of the ask and it will be the element that is emitted downstreams from mapAsync.

static class Translator extends UntypedActor {
  @Override
  public void onReceive(Object message) {
    if (message instanceof String) {
      String word = (String) message;
      // ... process message
      String reply = word.toUpperCase();
      // reply to the ask
      getSender().tell(reply, getSelf());
    } else {
      unhandled(message);
    }
  }
}

The stream can be completed with failure by sending akka.actor.Status.Failure as reply from the actor.

If the ask fails due to timeout the stream will be completed with TimeoutException failure. If that is not desired outcome you can use recover on the ask CompletionStage.

If you don't care about the reply values and only use them as back-pressure signals you can use Sink.ignore after the mapAsync stage and then actor is effectively a sink of the stream.

The same pattern can be used with Actor routers. Then you can use mapAsyncUnordered for better efficiency if you don't care about the order of the emitted downstream elements (the replies).

Sink.actorRefWithAck

The sink sends the elements of the stream to the given ActorRef that sends back back-pressure signal. First element is always onInitMessage, then stream is waiting for the given acknowledgement message from the given actor which means that it is ready to process elements. It also requires the given acknowledgement message after each stream element to make back-pressure work.

If the target actor terminates the stream will be cancelled. When the stream is completed successfully the given onCompleteMessage will be sent to the destination actor. When the stream is completed with failure a akka.actor.Status.Failure message will be sent to the destination actor.

Source.queue

Source.queue can be used for emitting elements to a stream from an actor (or from anything running outside the stream). The elements will be buffered until the stream can process them. You can offer elements to the queue and they will be emitted to the stream if there is demand from downstream, otherwise they will be buffered until request for demand is received.

Use overflow strategy akka.stream.OverflowStrategy.backpressure to avoid dropping of elements if the buffer is full.

SourceQueue.offer returns CompletionStage<QueueOfferResult> which completes with QueueOfferResult.enqueued if element was added to buffer or sent downstream. It completes with QueueOfferResult.dropped if element was dropped. Can also complete with QueueOfferResult.Failure - when stream failed or QueueOfferResult.QueueClosed when downstream is completed.

When used from an actor you typically pipe the result of the CompletionStage back to the actor to continue processing.

Source.actorRef

Messages sent to the actor that is materialized by Source.actorRef will be emitted to the stream if there is demand from downstream, otherwise they will be buffered until request for demand is received.

Depending on the defined OverflowStrategy it might drop elements if there is no space available in the buffer. The strategy OverflowStrategy.backpressure is not supported for this Source type, i.e. elements will be dropped if the buffer is filled by sending at a rate that is faster than the stream can consume. You should consider using Source.queue if you want a backpressured actor interface.

The stream can be completed successfully by sending akka.actor.PoisonPill or akka.actor.Status.Success to the actor reference.

The stream can be completed with failure by sending akka.actor.Status.Failure to the actor reference.

The actor will be stopped when the stream is completed, failed or cancelled from downstream, i.e. you can watch it to get notified when that happens.

Illustrating ordering and parallelism

Let us look at another example to get a better understanding of the ordering and parallelism characteristics of mapAsync and mapAsyncUnordered.

Several mapAsync and mapAsyncUnordered futures may run concurrently. The number of concurrent futures are limited by the downstream demand. For example, if 5 elements have been requested by downstream there will be at most 5 futures in progress.

mapAsync emits the future results in the same order as the input elements were received. That means that completed results are only emitted downstream when earlier results have been completed and emitted. One slow call will thereby delay the results of all successive calls, even though they are completed before the slow call.

mapAsyncUnordered emits the future results as soon as they are completed, i.e. it is possible that the elements are not emitted downstream in the same order as received from upstream. One slow call will thereby not delay the results of faster successive calls as long as there is downstream demand of several elements.

Here is a fictive service that we can use to illustrate these aspects.

static class SometimesSlowService {
  private final Executor ec;
  
  public SometimesSlowService(Executor ec) {
    this.ec = ec;
  }
  
  private final AtomicInteger runningCount = new AtomicInteger();

  public CompletionStage<String> convert(String s) {
    System.out.println("running: " + s + "(" + runningCount.incrementAndGet() + ")");
    return CompletableFuture.supplyAsync(() -> {
      if (!s.isEmpty() && Character.isLowerCase(s.charAt(0)))
        try { Thread.sleep(500); } catch (InterruptedException e) {}
      else
        try { Thread.sleep(20); } catch (InterruptedException e) {}
      System.out.println("completed: " + s + "(" + runningCount.decrementAndGet() + ")");
      return s.toUpperCase();
    }, ec);
  }
}

Elements starting with a lower case character are simulated to take longer time to process.

Here is how we can use it with mapAsync:

final Executor blockingEc = system.dispatchers().lookup("blocking-dispatcher");
final SometimesSlowService service = new SometimesSlowService(blockingEc);

final ActorMaterializer mat = ActorMaterializer.create(
  ActorMaterializerSettings.create(system).withInputBuffer(4, 4), system);

Source.from(Arrays.asList("a", "B", "C", "D", "e", "F", "g", "H", "i", "J"))
  .map(elem -> { System.out.println("before: " + elem); return elem; })
  .mapAsync(4, service::convert)
  .runForeach(elem -> System.out.println("after: " + elem), mat);

The output may look like this:

before: a
before: B
before: C
before: D
running: a (1)
running: B (2)
before: e
running: C (3)
before: F
running: D (4)
before: g
before: H
completed: C (3)
completed: B (2)
completed: D (1)
completed: a (0)
after: A
after: B
running: e (1)
after: C
after: D
running: F (2)
before: i
before: J
running: g (3)
running: H (4)
completed: H (2)
completed: F (3)
completed: e (1)
completed: g (0)
after: E
after: F
running: i (1)
after: G
after: H
running: J (2)
completed: J (1)
completed: i (0)
after: I
after: J

Note that after lines are in the same order as the before lines even though elements are completed in a different order. For example H is completed before g, but still emitted afterwards.

The numbers in parenthesis illustrates how many calls that are in progress at the same time. Here the downstream demand and thereby the number of concurrent calls are limited by the buffer size (4) of the ActorMaterializerSettings.

Here is how we can use the same service with mapAsyncUnordered:

final Executor blockingEc = system.dispatchers().lookup("blocking-dispatcher");
final SometimesSlowService service = new SometimesSlowService(blockingEc);

final ActorMaterializer mat = ActorMaterializer.create(
  ActorMaterializerSettings.create(system).withInputBuffer(4, 4), system);

Source.from(Arrays.asList("a", "B", "C", "D", "e", "F", "g", "H", "i", "J"))
  .map(elem -> { System.out.println("before: " + elem); return elem; })
  .mapAsyncUnordered(4, service::convert)
  .runForeach(elem -> System.out.println("after: " + elem), mat);

The output may look like this:

before: a
before: B
before: C
before: D
running: a (1)
running: B (2)
before: e
running: C (3)
before: F
running: D (4)
before: g
before: H
completed: B (3)
completed: C (1)
completed: D (2)
after: B
after: D
running: e (2)
after: C
running: F (3)
before: i
before: J
completed: F (2)
after: F
running: g (3)
running: H (4)
completed: H (3)
after: H
completed: a (2)
after: A
running: i (3)
running: J (4)
completed: J (3)
after: J
completed: e (2)
after: E
completed: g (1)
after: G
completed: i (0)
after: I

Note that after lines are not in the same order as the before lines. For example H overtakes the slow G.

The numbers in parenthesis illustrates how many calls that are in progress at the same time. Here the downstream demand and thereby the number of concurrent calls are limited by the buffer size (4) of the ActorMaterializerSettings.

Implementing Reactive Streams Publisher or Subscriber

As described above any Akka Streams Source can be exposed as a Reactive Streams Publisher and any Sink can be exposed as a Reactive Streams Subscriber. Therefore we recommend that you implement Reactive Streams integrations with built-in stages or custom stages.

For historical reasons the ActorPublisher and ActorSubscriber traits are provided to support implementing Reactive Streams Publisher and Subscriber with an Actor.

These can be consumed by other Reactive Stream libraries or used as an Akka Streams Source or Sink.

public static class JobManagerProtocol {
  final public static class Job {
    public final String payload;

    public Job(String payload) {
      this.payload = payload;
    }

  }

  public static class JobAcceptedMessage {
    @Override
    public String toString() {
      return "JobAccepted";
    }
  }
  public static final JobAcceptedMessage JobAccepted = new JobAcceptedMessage();

  public static class JobDeniedMessage {
    @Override
    public String toString() {
      return "JobDenied";
    }
  }
  public static final JobDeniedMessage JobDenied = new JobDeniedMessage();
}
public static class JobManager extends AbstractActorPublisher<JobManagerProtocol.Job> {

  public static Props props() { return Props.create(JobManager.class); }

  private final int MAX_BUFFER_SIZE = 100;
  private final List<JobManagerProtocol.Job> buf = new ArrayList<>();

  public JobManager() {
    receive(ReceiveBuilder.
      match(JobManagerProtocol.Job.class, job -> buf.size() == MAX_BUFFER_SIZE, job -> {
        sender().tell(JobManagerProtocol.JobDenied, self());
      }).
      match(JobManagerProtocol.Job.class, job -> {
        sender().tell(JobManagerProtocol.JobAccepted, self());

        if (buf.isEmpty() && totalDemand() > 0)
          onNext(job);
        else {
          buf.add(job);
          deliverBuf();
        }
      }).
      match(ActorPublisherMessage.Request.class, request -> deliverBuf()).
      match(ActorPublisherMessage.Cancel.class, cancel -> context().stop(self())).
      build());
  }

  void deliverBuf() {
    while (totalDemand() > 0) {
        /*
         * totalDemand is a Long and could be larger than
         * what buf.splitAt can accept
         */
      if (totalDemand() <= Integer.MAX_VALUE) {
        final List<JobManagerProtocol.Job> took =
          buf.subList(0, Math.min(buf.size(), (int) totalDemand()));
        took.forEach(this::onNext);
        buf.removeAll(took);
        break;
      } else {
        final List<JobManagerProtocol.Job> took =
          buf.subList(0, Math.min(buf.size(), Integer.MAX_VALUE));
        took.forEach(this::onNext);
        buf.removeAll(took);
      }
    }
  }
}

final Source<JobManagerProtocol.Job, ActorRef> jobManagerSource =
  Source.actorPublisher(JobManager.props());

final ActorRef ref = jobManagerSource
  .map(job -> job.payload.toUpperCase())
  .map(elem -> {
    System.out.println(elem);
    return elem;
  })
  .to(Sink.ignore())
  .run(mat);

ref.tell(new JobManagerProtocol.Job("a"), ActorRef.noSender());
ref.tell(new JobManagerProtocol.Job("b"), ActorRef.noSender());
ref.tell(new JobManagerProtocol.Job("c"), ActorRef.noSender());

public static class WorkerPoolProtocol {

  public static class Msg {
    public final int id;
    public  final ActorRef replyTo;

    public Msg(int id, ActorRef replyTo) {
      this.id = id;
      this.replyTo = replyTo;
    }

    @Override
    public String toString() {
      return String.format("Msg(%s, %s)", id, replyTo);
    }
  }
  public static Msg msg(int id, ActorRef replyTo) {
    return new Msg(id, replyTo);
  }


  public static class Work {
    public final int id;
    public Work(int id) { this.id = id; }

    @Override
    public String toString() {
      return String.format("Work(%s)", id);
    }
  }
  public static Work work(int id) {
    return new Work(id);
  }


  public static class Reply {
    public final int id;
    public Reply(int id) { this.id = id; }

    @Override
    public String toString() {
      return String.format("Reply(%s)", id);
    }
  }
  public static Reply reply(int id) {
    return new Reply(id);
  }


  public static class Done {
    public final int id;
    public Done(int id) { this.id = id; }

    @Override
    public String toString() {
      return String.format("Done(%s)", id);
    }

    @Override
    public boolean equals(Object o) {
      if (this == o) {
        return true;
      }
      if (o == null || getClass() != o.getClass()) {
        return false;
      }

      Done done = (Done) o;

      if (id != done.id) {
        return false;
      }

      return true;
    }

    @Override
    public int hashCode() {
      return id;
    }
  }
  public static Done done(int id) {
    return new Done(id);
  }

}

public static class WorkerPool extends AbstractActorSubscriber {

  public static Props props() { return Props.create(WorkerPool.class); }

  final int MAX_QUEUE_SIZE = 10;
  final Map<Integer, ActorRef> queue = new HashMap<>();

  final Router router;

  @Override
  public RequestStrategy requestStrategy() {
    return new MaxInFlightRequestStrategy(MAX_QUEUE_SIZE) {
      @Override
      public int inFlightInternally() {
        return queue.size();
      }
    };
  }

  public WorkerPool() {
    final List<Routee> routees = new ArrayList<>();
    for (int i = 0; i < 3; i++)
      routees.add(new ActorRefRoutee(context().actorOf(Props.create(Worker.class))));
    router = new Router(new RoundRobinRoutingLogic(), routees);

    receive(ReceiveBuilder.
    match(ActorSubscriberMessage.OnNext.class, on -> on.element() instanceof WorkerPoolProtocol.Msg,
      onNext -> {
        WorkerPoolProtocol.Msg msg = (WorkerPoolProtocol.Msg) onNext.element();
        queue.put(msg.id, msg.replyTo);

        if (queue.size() > MAX_QUEUE_SIZE)
          throw new RuntimeException("queued too many: " + queue.size());

        router.route(WorkerPoolProtocol.work(msg.id), self());
    }).
    match(ActorSubscriberMessage.onCompleteInstance().getClass(), complete -> {
      if (queue.isEmpty()) {
        context().stop(self());
      }
    }).
    match(WorkerPoolProtocol.Reply.class, reply -> {
      int id = reply.id;
      queue.get(id).tell(WorkerPoolProtocol.done(id), self());
      queue.remove(id);
      if (canceled() && queue.isEmpty()) {
        context().stop(self());
      }
    }).
    build());
  }
}

static class Worker extends AbstractActor {
  public Worker() {
    receive(ReceiveBuilder.
      match(WorkerPoolProtocol.Work.class, work -> {
        // ...
        sender().tell(WorkerPoolProtocol.reply(work.id), self());
      }).build());
  }
}

final int N = 117;
final List<Integer> data = new ArrayList<>(N);
for (int i = 0; i < N; i++) {
  data.add(i);
}

final ActorRef worker = Source.from(data)
  .map(i -> WorkerPoolProtocol.msg(i, replyTo))
  .runWith(Sink.<WorkerPoolProtocol.Msg>actorSubscriber(WorkerPool.props()), mat);