Skip to content

Stream Events ​

An Rx stream talks to its subscriber with four events. OnNext carries a value, and OnError reports an error that the stream continues past. The stream ends at most once: with OnCompletion when it completed, or with OnFailure when it failed. Read this page when you write a handler that sees events, rather than just values, or when you need to know whether and how a stream ends.

scala
import wvlet.uni.rx.*

RxRunner.runContinuously(Rx.fromSeq(Seq(1, 2, 3))) {
  case OnNext(v)    => println(s"value: ${v}")
  case OnError(e)   => println(s"error, the stream goes on: ${e.getMessage}")
  case OnCompletion => println("completed")
  case OnFailure(e) => println(s"failed: ${e.getMessage}")
}
// value: 1
// value: 2
// value: 3
// completed

The Four Events ​

EventMeaningWhat comes after it
OnNext(v)A valueMore events
OnError(e)An error the stream continues past, such as a throwing map functionMore events
OnCompletionThe stream completedNothing
OnFailure(e)The stream failed, for example because its source failedNothing

OnCompletion and OnFailure share the parent type OnEnd. Match case end: OnEnd when you only need to know that the stream ended.

The Rules ​

  1. Values and errors arrive in any order, then at most one end. A stream's events always follow the shape (OnNext | OnError)* (OnCompletion | OnFailure)?.
  2. Nothing follows an end. After OnCompletion or OnFailure, the subscription is over.
  3. A stream can run forever. An Rx.variable or an Rx.interval has no end until you stop it, so cancel the Cancelable that subscribe returns when you are done with it.
  4. An end carries no value. Values arrive only as OnNext. For the last value, use lastOption, which emits Some(last), or None for an empty stream, before it completes.

Two Kinds of Errors ​

An error that happens inside the stream doesn't end it. A throwing map reports an OnError, and the next value still arrives:

scala
val parsed = Rx.fromSeq(Seq("1", "x", "3")).map(_.toInt)
// OnNext(1), OnError(NumberFormatException), OnNext(3), OnCompletion

A failed source ends the stream with OnFailure, because nothing more can come from it. Examples are Rx.exception(e), a throwing Rx.single { ... }, a failed Rx.future, and RxVar.setException(e):

scala
val failed = Rx.exception[Int](IllegalStateException("unavailable"))
// OnFailure(IllegalStateException)

recover handles both kinds. For an OnError, it emits the replacement value and the stream goes on. For an OnFailure, it emits the replacement value and completes:

scala
val recovered = parsed.recover { case _: NumberFormatException => 0 }
// OnNext(1), OnNext(0), OnNext(3), OnCompletion

val fallback = failed.recover { case _: IllegalStateException => -1 }
// OnNext(-1), OnCompletion

In the gallery, each lane draws the events of one stream: the throwing map goes on past its error, while Rx.exception and a failed Rx.future end, and recover replaces each error with a value. A failed RxVar ends the same way; see recoverWith.

Event Traces ​

What a handler of RxRunner.runContinuously receives, where boom is a map that throws on 2:

StreamEvents
Rx.fromSeq(Seq(1, 2, 3))OnNext(1) OnNext(2) OnNext(3) OnCompletion
Rx.empty[Int]OnCompletion
Rx.single(1)OnNext(1) OnCompletion
Rx.exception(e)OnFailure(e)
Rx.future(f), where f fails with eOnFailure(e)
Rx.fromSeq(Seq(1, 2, 3)).map(boom)OnNext(1) OnError(e) OnNext(3) OnCompletion
Rx.fromSeq(Seq(1, 2, 3)).filter(_ > 10)OnCompletion
Rx.fromSeq(Seq(1, 2, 3)).take(2)OnNext(1) OnNext(2) OnCompletion
Rx.fromSeq(Seq(1, 2, 3)).lastOptionOnNext(Some(3)) OnCompletion
Rx.fromSeq(Seq(1, 2)).concat(Rx.single(3))OnNext(1) OnNext(2) OnNext(3) OnCompletion
Rx.exception(e).concat(Rx.single(3))OnFailure(e)
Rx.fromSeq(Seq(1, 2, 3)).map(boom).materializeOnNext(Success(1)) OnNext(Failure(e)) OnCompletion

filter doesn't complete a stream when it rejects a value. It reports the end of its upstream, so it completes here only because the sequence did. concat starts its second stream only after the first one completes. materialize turns events into Result values, and it ends at the first error.

Each lane in the gallery runs one of these streams. Press Replay to run them again:

Variables ​

An Rx.variable sends its current value to each new subscriber. After that, it sends each new value; setting the same value again sends nothing (use forceSet to send it anyway). It has no end until you call stop() or setException(e):

scala
val counter = Rx.variable(0)
val c = RxRunner.runContinuously(counter)(ev => println(ev))
// OnNext(0)
counter := 1 // OnNext(1)
counter := 1 // nothing: the value did not change
counter.stop() // OnCompletion

counter.setException(e) ends the variable with OnFailure(e) instead. Try each step in the gallery. Subscribe again starts a new subscription, which gets the current value at once:

Ways to Run a Stream ​

Each entry point decides what your code sees:

Entry pointYour code receivesAt an OnErrorAt the end
rx.subscribe(f)ValuesLogged as a warning, and the stream goes onStops; an OnFailure is logged as a warning
RxRunner.runContinuously(rx)(f)Every RxEventDelivered, and the stream goes onDelivered, then stops
RxRunner.run(rx)(f)OnNext, OnCompletion, OnFailureDelivered as OnFailure(e), and the run stopsDelivered, then stops
RxRunner.runOnce(rx)(f)The first event onlyDelivered as OnFailure(e) if it comes firstDelivered if it comes first
rx.run(f)ValuesThrown, and the run stopsStops, and an OnFailure is thrown
rx.toSeq, rx.await (JVM and Native)All values, or the first oneThrownReturns

RxRunner.run suits one-shot work such as a request, where the first error is the answer. Its handler type, RxRunEvent, has no OnError case, so the compiler checks three cases:

scala
RxRunner.run(parsed) {
  case OnNext(v)    => println(s"value: ${v}")
  case OnCompletion => println("done")
  case OnFailure(e) => println(s"failed: ${e.getMessage}")
}
// value: 1
// failed: For input string: "x"

In the gallery, the same stream runs with runContinuously and with run side by side. When n reaches 3, the run lane ends with a failure, while the runContinuously lane draws an error and goes on:

subscribe suits UI state and other long-lived streams. Its function sees values only. An error it can't handle is logged as a warning, never thrown back to the code that sent the event, such as the caller of :=. Handle errors in the chain with recover or tapOnFailure, or use RxRunner.runContinuously to see every event. A uni-dom binding shows nothing for an OnError and renders the next value.

How Operators End ​

OperatorCompletes when
map, filter, tapIts upstream ends
take(n)It has emitted n values (it cancels its upstream), or its upstream ends first
concat(other)other ends; an OnFailure of the first stream ends it at once
flatMap(f)Both its input and the current inner stream have ended; a new input value cancels the inner stream still running
zip(...)One of its sources has ended and has no buffered value left to pair
join(...)Every source has ended
recover(f)Its upstream completes, or after the replacement value for an OnFailure

An OnFailure of an inner stream of flatMap, or of any source of merge, ends the operator with the same failure.

Compared With Other Rx Libraries ​

Uni's events follow R3 for .NET, which also separates errors a stream continues past from the end of a stream:

UniR3ReactiveX (RxJava)
OnNext(v)OnNext(v)onNext(v)
OnError(e), the stream goes onOnErrorResume(e)(no equivalent)
OnCompletionOnCompleted(Result.Success)onComplete()
OnFailure(e)OnCompleted(Result.Failure(e))onError(e)

In ReactiveX, every error ends the stream. In Uni, only OnFailure does. RxRunner.run gives you ReactiveX's behavior by delivering the first error as the end.

Released under the Apache 2.0 License.