Add Promise style semantics to reactive streams

[daviddawson]

We are currently building a set of network APIs that use reactive streams. We're migrating more and more over the reactive streams to gain the benefits of swappable implementations over the standardised interfaces, back pressure support and good FRP.

When dealing with streaming data, the semantics are well understood by the users of the API. When dealing with something that is naturally request/ response (think similar to an HTTP request), then the semantics begin to break down.

We used a Future for this reason. Developers approaching the API expect to get a single response back, and we feel that the API should indicate to them what they should expect to happen. It's about reasoning and learning rather than mechanics.

Naturally, we would want to return a Promise from this type of API, indicating to the developer what they can reasonably expect to occur. Currently, our only option from reactive streams is a full publisher.

Mechanically, this works fine, but that isn't the issue. From the point of view of building an API for consumption by randoms on the internet, I don't want to have to indicate in the method name nor the documentation that a single item will be returned.

The case of up to 1 item being returned is special, and has spawned Future and Promise in the JDK and everywhere else respectively. For this reason, and for reactive streams to become even more useful for the developing of highly interoperable and usable APIs, I would like to suggest that a Promise interface be added to the core set.

Mechnically, it would be an extension of Publisher, and nothing more. Semantically, it would be constrained in the specification to return up to a single item.

[viktorklang]

@daviddawson Given that we're talking about an end-user API, would it make sense to use CompletionStage in stead of the RS interfaces for these kinds of methods? (It would be a rather trivial exercise to write a bridge between CompletionStage and Publisher if one needs to pass one as the other).
Let me know what you think!

[jbrisbin]

@viktorklang Good idea, but needs to support Java 7 as a minimum IMO.

[jbrisbin]

I think this is somewhat related as well: in the @reactive-ipc/reactive-ipc-jvm project we're [ab]using the RS API to indicate completion or error state by using a Publisher<Void>. This means you'll never get a real value, only a notification of complete or error. I'm thinking that with a "real" Promise style interface, we could be using that specific indicator rather than the somewhat arbitrary use of the Publisher. The former indicates a more promissory intent IMO than Publisher<Void> which is technically fine and correct but just doesn't feel right to me. It feels like we're trying to get the benefits of the interoperability of the RS API so we can compose actions based on this but since a Publisher is meant to transmit values, it seems odd to me that we would specify Publisher<Void> which really means "values of type NULL"--which is the only possible value of the Void type. Since that's illegal, what we're saying is "use this technically illegal signature to express the intent that an operation will be completed later and will result in a complete or error state but will not have any associated value".

This type of situation has come up for us quite a few times and I really think that providing for it at the RS level is better because it allows us to stick to that API rather than extending it to our own and requiring some other kind of component that isn't sharable like the RS API is.

[daviddawson]

Yes, I'd like Java 7 support.

Also, tbh CompletionStage is a bit opaque on how it should be handled by a user :-)

Reactor in particular exposes the reactive streams interfaces all over the place, so having a potential Promise there too would be fairly natural. If a Promise in reactive streams were just defined as

interface Promise extends Publisher {}

Then it would be totally non invasive and integrate with existing reactive streams implementations while extending the semantics of reactive streams into an area ripe for it.

Thinking about it, we'll do this anyway (define a Promise interface), but it would be good to have it standardised.

[jbrisbin]

I would like to take it one step further and specifically call out the special case of Promise<Void> to make sure it's noted that since the spec prohibits null values already, that a Promise<Void> indicates 0 values and a Promise<T> indicates 0-1 values.

[viktorklang]

First, let me state that I am not trying to be a contrarian, or otherwise be difficult—I'm merely trying to see if there is a problem worth solving here, and if it is worth solving or if there is alternate solutions that would work in the place of the proposed solution.

@viktorklang Good idea, but needs to support Java 7 as a minimum IMO.

@jbrisbin Normally I would agree, but given that J7 is EOL and that it is possible to run j.u.c.CompletionStage via -Xbootclasspath if one must target an obsolete platform, does it really make sense to add yet another thing that maps directly to a JDK type?

I think this is somewhat related as well: in the @reactive-ipc/reactive-ipc-jvm project we're [ab]using the RS API to indicate completion or error state by using a Publisher. This means you'll never get a real value, only a notification of complete or error. I'm thinking that with a "real" Promise style interface, we could be using that specific indicator rather than the somewhat arbitrary use of the Publisher. The former indicates a more promissory intent IMO than Publisher which is technically fine and correct but just doesn't feel right to me.

But Promise wouldn't be better than Publisher? It's still no value expected, right?

, it seems odd to me that we would specify Publisher which really means "values of type NULL"--which is the only possible value of the Void type. Since that's illegal, what we're saying is "use this technically illegal signature to express the intent that an operation will be completed later and will result in a complete or error state but will not have any associated value".

Technically "Void" could be correct here, but the problem I see is that its Javadoc is terrible: https://docs.oracle.com/javase/6/docs/api/java/lang/Void.html

In a language with a more…sophisticated…type system one would use something more like Publisher[Nothing].

So what you could do instead is to define:

/**
 * A type that indicates that no value of this type can exist.
 */
public enum Nothing {;}

and then use:

Publisher<Nothing>

This type of situation has come up for us quite a few times and I really think that providing for it at the RS level is better because it allows us to stick to that API rather than extending it to our own and requiring some other kind of component that isn't sharable like the RS API is.

Agreed. But do you agree that the existence of CompletionStage and the EOL of Java7 diminishes the value of creating this new type, adding speccing for it, updating the TCK for it, updating the docs for it and having to ship a new version of RS. For a single marker interface? (Me remembering how hard I had to argue to get Processor approved by @benjchristensen back in the days.)

[jbrisbin]

@viktorklang I would expect you and @benjchristensen to push back on most things as it ends up being better for having people who don't just agree right away but pick at the solution and ask tough questions. I don't see anything wrong with being a contrarian! ;)

@jbrisbin Normally I would agree, but given that J7 is EOL and that it is possible to run j.u.c.CompletionStage via -Xbootclasspath if one must target an obsolete platform, does it really make sense to add yet another thing that maps directly to a JDK type?

Have to disagree pretty completely here. I realize that Java 7 is technically EOL but in the real world that makes no difference (and the bootclasspath option is a non-starter...I can't imagine the discussion with ops that would ensue to describe the need to add a custom JVM option to be distributed with the application...that is an unreasonable burden IMO). The fact of life is that it's unrealistic for someone writing applications designed to be adopted by folks still using legacy applications to upgrade to Java 8 just to get a simple feature that can be provided by an earlier JDK. I don't agree that the JDK 8 type adds anything meaningful (par for the course...there's me being the contrarian!).

But Promise wouldn't be better than Publisher? It's still no value expected, right?

True, but I think we need to address the use specifically because what we're saying is not "null values", which is really what Publisher<Void> is saying. As you pointed out, the JDK has no way of saying "nothing" so we're stuck with Void which is close but IMO still not correct.

But do you agree that the existence of CompletionStage and the EOL of Java7 diminishes the value of creating this new type, adding speccing for it, updating the TCK for it, updating the docs for it and having to ship a new version of RS. For a single marker interface? (Me remembering how hard I had to argue to get Processor approved by @benjchristensen back in the days.)

I don't think the effort of including it weighs on its usefulness. Those may be logistical hurdles to overcome but they shouldn't be factors in deciding whether or not the Promise has merit.

I believe it is important to include in the core RS API (one which gets reused and is guided and documented by a concomitant specification) a component for expressing the intent that a Publisher isn't just a "normal" Publisher but that you can guarantee either zero or 1 onNext plus an onComplete. The important thing as @daviddawson pointed out is that you can do this already but it's imprecise in code. It's technically correct to return a Publisher<T> but it's very vague about what expectations there are around that Publisher. In most cases that's good because it allows easy interoperability. But I know of two implementations of Reactive Streams (Reactor and Ratpack) that have their own, somewhat competing implementations of Promise. There's also Netty itself, which has a promise capability that we're trying to "convert" to the RS API. This divergence can't be good and could be avoided by providing in the RS spec a facility for expressing a sort-of-future-like component that expresses the idea of a single (or no) result + a complete.

[jbrisbin]

Technically "Void" could be correct here, but the problem I see is that its Javadoc is terrible: https://docs.oracle.com/javase/6/docs/api/java/lang/Void.html

In a language with a more…sophisticated…type system one would use something more like Publisher[Nothing]`.

So what you could do instead is to define:

/**
 * A type that indicates that no value of this type can exist.
 */
public enum Nothing {;}

That's definitely more explicit (and likely preferable) but I don't know that it does anything meaningful more than Void.

The one subtle thing that might argue in its favor is that enum Nothing {;} really does mean "nothing" because there's no way to communicate a value. With Void you're really getting a wrapper class that has a public static member of type Class<Void>. That's generally understood to mean "null" and not "nothing" which IMO is the core of the problem.

Publisher<Optional<T>> could be interesting as well, but you're back to the problem of being Java 8-only.

[jbrisbin]

Maybe @daviddawson and @smaldini could comment (and feel free to disagree if you want!) but I think we need two classes and two specification provisions:

public interface Promise<T> extends Publisher<T> {}

public enum Nothing {;}

The Promise<T> is spec'd to provide for a special kind of Publisher that a user can know for certain will never have more than 1 onNext signal plus the onComplete.

The Promise<Nothing> is spec'd to provide for a special situation where a Publisher will never receive an onNext signal, only an onComplete or onError. It doesn't necessarily have to be part of the TCK I don't think but could be a provision on one of the Promise rules that specifies in a predictable way what to expect if that is used in a library.

The reason for including these here is that this is the lowest common denominator when writing libraries that expose their Reactive Streams support. It seems less useful to have LibraryA create their own version of Publisher<T> that is effectually a Promise and LibraryB create their own version which does things a little differently. Both exhibit similar characteristics but neither clearly expresses the intent of how they're using a Publisher.

The alternative is to defer dealing with this to implementations and get what we have today which is very vague and not interoperable (I can't communicate the idea of a Promise from one library to the next, only a Publisher) and will lead to gaps with using the RS API where we have to supplement it with our own components.

[daviddawson]

I strongly agree. I would very much like to have a standardised Promise whose primary purpose is interop between FRP style libraries and application stacks.

As an experiment, I just implemented a Promise across a test codebase where previously it was Publisher and and it becomes much clearer what does what. Looking through the Reactor codebase a little, I can see that a standardised interface could be retrofitted in there too and help clear things up (although since there's an internal Promise already, possibly not so much)

The other interface (Nothing) I'm not sure I've seen the need yet, but I understand your description and could see it being useful for us in the future.

I agree with @jbrisbin on standardisation. There are half a dozen Promise implementations now extant in the codebases we use regularly, and they are starting to grow in functionality to mean something more like 'stream processing' than 'I may give you something later' (looking at the Ratpack one in particular). If an attempt isn't made to give some interop under the purview of the reactive streams specifications, then I don't see any interop being possible around this concept, which I think would be a shame.

Also, this is too easy to pass up, my apologies.

public interface Promise<T> extends Publisher<T> {}

public enum YouAreDeadToMe {;}

Promise<YouAreDeadToMe>();

[jbrisbin]

public interface Promise<T> extends Publisher<T> {}

public enum YouAreDeadToMe {;}

Promise<YouAreDeadToMe>();

😆

[ldaley]

One of the benefits of using a promise (a.k.a. a one, or zero-or-one depending on perspective, element stream) is that you don't have to worry about demand, hot vs. cold, async cancellation (i.e. in that it's simpler). Promise<T> extends Publisher<T> defeats this. You're still carrying all the complexity of Publisher.

You can easily adapt a promise to/from Publisher. That seems like a better strategy for end user API.

[viktorklang]

@viktorklang I would expect you and @benjchristensen to push back on most things as it ends up being better for having people who don't just agree right away but pick at the solution and ask tough questions. I don't see anything wrong with being a contrarian! ;)

Thanks for being extremely understanding of the reason! :)
There's going to be a lot in this reply that can be perceived as me being negative (and I detest feeling like I'm only being negative) so please, please take everything I say below as the most constructive criticism I can bring forth after only getting 4.5h of sleep (thanks kids!).

Have to disagree pretty completely here. I realize that Java 7 is technically EOL but in the real world that makes no difference (and the bootclasspath option is a non-starter...I can't imagine the discussion with ops that would ensue to describe the need to add a custom JVM option to be distributed with the application...that is an unreasonable burden IMO). The fact of life is that it's unrealistic for someone writing applications designed to be adopted by folks still using legacy applications to upgrade to Java 8 just to get a simple feature that can be provided by an earlier JDK. I don't agree that the JDK 8 type adds anything meaningful (par for the course...there's me being the contrarian!).

Why don't you think the JDK8 type adds anything meaningful? The entire purpose of adding it was to accommodate for exactly this type of thing, at least that's what I recall from talking to @DougLea.

True, but I think we need to address the use specifically because what we're saying is not "null values", which is really what Publisher is saying. As you pointed out, the JDK has no way of saying "nothing" so we're stuck with Void which is close but IMO still not correct.

But if Promise does not solve the problem, why add it?

I don't think the effort of including it weighs on its usefulness. Those may be logistical hurdles to overcome but they shouldn't be factors in deciding whether or not the Promise has merit.

If logistical hurdles are not to be taken into account, then requiring people to go through the logistical hurdle of upgrading to JDK8 shouldn't be an issue either, right? :-)

I believe it is important to include in the core RS API (one which gets reused and is guided and documented by a concomitant specification) a component for expressing the intent that a Publisher isn't just a "normal" Publisher but that you can guarantee either zero or 1 onNext plus an onComplete.

So it guarantees that onError will never be signalled?

The important thing as @daviddawson pointed out is that you can do this already but it's imprecise in code. It's technically correct to return a Publisher but it's very vague about what expectations there are around that Publisher.

Understood. But where does it stop?

Do we need a Publisher type for something that only ever signals onComplete?
Do we need a Publisher type for something that only ever signals onError?
Do we need a Publisher type for something that signals 0…1 of any element and then onComplete?
Do we need a Publisher type for something that signals 0…1 of any element and then onComplete OR onError?
Do we need a Publisher type for something that signals 0…1 and ALWAYS the same element then onComplete?
Do we need a Publisher type for something that signals 0…1 and ALWAYS the same element then onComplete OR onError?
Do we need a Processor type for each of the permutations above?
How does all of these types relate to Subscriber? Because every Subscriber would still have to be written with the assumption of of Publisher, or do we need permutations of Subscriber for all of the above?

Reading the above, it is also clear that the definition of Promise is unclear, in my world a promise only ever produces the same result (deterministic) for all Subscribers, but a Publisher of 0…1 elements could send different elements to each. (hot/cold distinction)

In most cases that's good because it allows easy interoperability. But I know of two implementations of Reactive Streams (Reactor and Ratpack) that have their own, somewhat competing implementations of Promise. There's also Netty itself, which has a promise capability that we're trying to "convert" to the RS API. This divergence can't be good and could be avoided by providing in the RS spec a facility for expressing a sort-of-future-like component that expresses the idea of a single (or no) result + a complete.

The attempt of unifying these is CompletionStage for the JDK.
We used to have the same situation for Scala back in the days before I got involved in SIP-14 to standardize on scala.concurrent.Future, which required everyone to update to the Scala version which included it for interop (equivalent to requiring upgrade to JDK8 AFAICT).

The Promise is spec'd to provide for a special kind of Publisher that a user can know for certain will never have more than 1 onNext signal plus the onComplete.

But that's not the definition of a promise. A promise needs to publish the -same- element to all consumers (deterministic).

The Promise is spec'd to provide for a special situation where a Publisher will never receive an onNext signal, only an onComplete or onError. It doesn't necessarily have to be part of the TCK I don't think but could be a provision on one of the Promise rules that specifies in a predictable way what to expect if that is used in a library.

Having thought about it for a while, I think there's enough prior art to use Void: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html

(In Scala one'd use Nothing (the bottom type) since it has other implications from a type system perspective).

The reason for including these here is that this is the lowest common denominator when writing libraries that expose their Reactive Streams support. It seems less useful to have LibraryA create their own version of Publisher that is effectually a Promise and LibraryB create their own version which does things a little differently. Both exhibit similar characteristics but neither clearly expresses the intent of how they're using a Publisher.

Publisher generically is not effectually a Promise (from the definition I use) since Publisher does not distinguish hot/cold, and this for a reason, because it creates a terrible matrix of permutations, tracking hotness/coldness through combinators is a real pain, and that doesn't even take into the account things like never-completes, never-fails situations.

The alternative is to defer dealing with this to implementations and get what we have today which is very vague and not interoperable (I can't communicate the idea of a Promise from one library to the next, only a Publisher) and will lead to gaps with using the RS API where we have to supplement it with our own components.

The RS API is for interop (not end user, since it doesn't have any combinators or otherwise) and given my argumentation around the permutations I don't see the adding of a Promise interface as something that carries its weight from a utility PoV (especially considering j.u.c.CompletionStage)

@daviddawson

I strongly agree. I would very much like to have a standardised Promise whose primary purpose is interop between FRP style libraries and application stacks.

There is a standardised Promise! :)
https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html

As an experiment, I just implemented a Promise across a test codebase where previously it was Publisher and and it becomes much clearer what does what. Looking through the Reactor codebase a little, I can see that a standardised interface could be retrofitted in there too and help clear things up (although since there's an internal Promise already, possibly not so much)

Turning a Promise into a Publisher is very simple, as @alkemist pointed out, if you want to go in that direction and it's even simpler if you control your own Promise interface (since Java still doesn't have things like extension methods/typeclasses) as you can add a "toPublisher" method on it, don't you agree?

The other interface (Nothing) I'm not sure I've seen the need yet, but I understand your description and could see it being useful for us in the future.

It improves over Void in the sense that it can be properly documented as to its purpose where j.l.Void is poorly documented in that regard.

I agree with @jbrisbin on standardisation. There are half a dozen Promise implementations now extant in the codebases we use regularly, and they are starting to grow in functionality to mean something more like 'stream processing' than 'I may give you something later' (looking at the Ratpack one in particular). If an attempt isn't made to give some interop under the purview of the reactive streams specifications, then I don't see any interop being possible around this concept, which I think would be a shame.

While unification of Future/Promise implementations is a worthy goal (which I contend is solved in jdk8 with CompletionStage), Promises isn't what Reactive Streams sets out to solve (even if I am very fond of Promises:

*Reactive Streams is an initiative to provide a standard for asynchronous stream processing with non-blocking back pressure.*

One of the benefits of using a promise (a.k.a. a one, or zero-or-one depending on perspective, element stream) is that you don't have to worry about demand, hot vs. cold, async cancellation (i.e. in that it's simpler). Promise extends Publisher defeats this. You're still carrying all the complexity of Publisher.

👍 Also, Futures/Promises are typically not demand driven.

You can easily adapt a promise to/from Publisher. That seems like a better strategy for end user API.

I'll have to side with @alkemist on this one!

[smaldini]

I'm aligned with @viktorklang on that I would not encourage a generic extension for this. There are however things to clarify in the specification about the contract around this I agree tho.

[jbrisbin]

@viktorklang Thanks for taking the time to respond thoroughly. I disagree with you and I suspect we'll have to just leave it at that. But your input is appreciated!

I don't want to address individual points because I don't want to drag this out since I don't see any solution hovering over the horizon, just more ocean. But I do want to clarify a few things for the sake of people reading later:

1. CompletionStage is a non-starter. We (Reactor/Spring) are simply not going to throw away all the users that can't upgrade to JDK 8. Period. The CompletableFuture API is also...I'll stop there (mom always said "if you can't say anything nice, don't say anything at all"...following that advice).

2. My point about logistical hurdles applies to things we control and set out to do. It's a different thing entirely to put expectations on users that involve a pretty significant change to how they do things. I don't think it's a good idea to say "well that would be hard to do" as an argument on the merit of something. Either it has real value or it doesn't. The amount of work involved in implementing it may be a reason to say "yes, it has value but we can't afford to pursue it". I simply wanted to argue the case on the merits as it pertains to application and library developers without burdening it with other concerns. Those can come later.

3. A Promise has no other characteristics different from a Publisher other than the expectation of what will published via onNext. It is still completely demand-driven (a "hot" stream might very well also have a value ready just like a Promise so in that case is indistinguishable). It still terminates with onComplete or onError. It is simply a Publisher with additional expectations that have been spec'd and documented so that library authors can rely on the behavior.

4. Various solutions already exist to implement this behavior because it's a natural progression from "pure" RS to a "real" application. There are and will continue to be "competing" implementations even though there doesn't have to be. In order to have interop, we will have to use Publisher as the only means to do that since there's no other way provided.

Reactor will be happy to continue doing what we're doing by providing a Promise implementation that provides a good API and fills the gap between a pure RS Publisher and the application code that expects there to be a single response to a request they've submitted. But it's such a common use case that it seems a shame to not be able to provide for it in the core API. When building libraries that expose the RS API for interop, devs will simply have to say: "we'd like to just use RS by itself but since we need a Promise we can't do that so we have to depend on this other library X which does provide it...hope that doesn't interfere with library Y, which you're also using and which also provides a different kind of Promise to the one we're using...wish it were different but it ain't so there ya go!"