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.
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
// completedThe Four Events
| Event | Meaning | What comes after it |
|---|---|---|
OnNext(v) | A value | More events |
OnError(e) | An error the stream continues past, such as a throwing map function | More events |
OnCompletion | The stream completed | Nothing |
OnFailure(e) | The stream failed, for example because its source failed | Nothing |
OnCompletion and OnFailure share the parent type OnEnd. Match case end: OnEnd when you only need to know that the stream ended.
The Rules
- Values and errors arrive in any order, then at most one end. A stream's events always follow the shape
(OnNext | OnError)* (OnCompletion | OnFailure)?. - Nothing follows an end. After
OnCompletionorOnFailure, the subscription is over. - A stream can run forever. An
Rx.variableor anRx.intervalhas no end until you stop it, so cancel theCancelablethatsubscribereturns when you are done with it. - An end carries no value. Values arrive only as
OnNext. For the last value, uselastOption, which emitsSome(last), orNonefor 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:
val parsed = Rx.fromSeq(Seq("1", "x", "3")).map(_.toInt)
// OnNext(1), OnError(NumberFormatException), OnNext(3), OnCompletionA 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):
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:
val recovered = parsed.recover { case _: NumberFormatException => 0 }
// OnNext(1), OnNext(0), OnNext(3), OnCompletion
val fallback = failed.recover { case _: IllegalStateException => -1 }
// OnNext(-1), OnCompletionIn 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:
| Stream | Events |
|---|---|
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 e | OnFailure(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)).lastOption | OnNext(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).materialize | OnNext(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):
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() // OnCompletioncounter.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 point | Your code receives | At an OnError | At the end |
|---|---|---|---|
rx.subscribe(f) | Values | Logged as a warning, and the stream goes on | Stops; an OnFailure is logged as a warning |
RxRunner.runContinuously(rx)(f) | Every RxEvent | Delivered, and the stream goes on | Delivered, then stops |
RxRunner.run(rx)(f) | OnNext, OnCompletion, OnFailure | Delivered as OnFailure(e), and the run stops | Delivered, then stops |
RxRunner.runOnce(rx)(f) | The first event only | Delivered as OnFailure(e) if it comes first | Delivered if it comes first |
rx.run(f) | Values | Thrown, and the run stops | Stops, and an OnFailure is thrown |
rx.toSeq, rx.await (JVM and Native) | All values, or the first one | Thrown | Returns |
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:
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
| Operator | Completes when |
|---|---|
map, filter, tap | Its 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:
| Uni | R3 | ReactiveX (RxJava) |
|---|---|---|
OnNext(v) | OnNext(v) | onNext(v) |
OnError(e), the stream goes on | OnErrorResume(e) | (no equivalent) |
OnCompletion | OnCompleted(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.