Flow.Subscription's javadoc

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Flow.Subscription's javadoc

Pavel Rappo
Hi,

    /**
     * Message control linking a {@link Publisher} and {@link
     * Subscriber}.  Subscribers receive items only when requested,
     * and may cancel at any time. The methods in this interface are
     * intended to be invoked only by their Subscribers; usages in
     * other contexts have undefined effects.
     */
    public static interface Subscription

Could anyone please explain what the "The methods in this interface are intended
to be invoked only by their Subscribers; usages in other contexts have undefined
effects." part is all about? (or 3.1 [1])

I'm sure I understand the relationship between a subscriber and its subscription
to a certain publisher. What I'm not sure about is that I understand what
constitutes the "context" mentioned in the javadoc above.

For example, can a subscriber invoke Subscription.request NOT in a response to
Subscriber.onNext or Subscriber.onSubscribe? Or in the general case, delegate
the responsibility to replenish requests to someone else (e.g. to let
Subscription.request be triggered by outer events)?

Thanks.

--------------------------------------------------------------------------------
[1] https://github.com/reactive-streams/reactive-streams-jvm/#3-subscription-code
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Flow.Subscription's javadoc

Dávid Karnok
I must admit that sounds a bit of a weak guarantee. In RxJava 2 and reactive-streams-commons, Subscription implementations are thread safe and reentrant-safe, thus request and cancel can be called at any time from any thread, even immediately from onSubscribe. What I can deduce, Flow.SubmissionPublisher has also this property.

However, the spec indicates that the link itself is a private matter between Publisher and Subscriber and if you want to expose, for example, cancel() to the outside world in your MySubscriber(), extra care has to be taken inside MySubscriber. Same goes for request(). Here [1][2] is an example of a Subscriber that allows external cancellation and requests.

Bottom line is, that if you can get hold of a Subscription, you won't break the upstream but you may break a downstream if it didn't expect more values you just requested.

-------------

2016-01-29 17:26 GMT+01:00 Pavel Rappo <[hidden email]>:
Hi,

    /**
     * Message control linking a {@link Publisher} and {@link
     * Subscriber}.  Subscribers receive items only when requested,
     * and may cancel at any time. The methods in this interface are
     * intended to be invoked only by their Subscribers; usages in
     * other contexts have undefined effects.
     */
    public static interface Subscription

Could anyone please explain what the "The methods in this interface are intended
to be invoked only by their Subscribers; usages in other contexts have undefined
effects." part is all about? (or 3.1 [1])

I'm sure I understand the relationship between a subscriber and its subscription
to a certain publisher. What I'm not sure about is that I understand what
constitutes the "context" mentioned in the javadoc above.

For example, can a subscriber invoke Subscription.request NOT in a response to
Subscriber.onNext or Subscriber.onSubscribe? Or in the general case, delegate
the responsibility to replenish requests to someone else (e.g. to let
Subscription.request be triggered by outer events)?

Thanks.

--------------------------------------------------------------------------------
[1] https://github.com/reactive-streams/reactive-streams-jvm/#3-subscription-code
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest



--
Best regards,
David Karnok

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Flow.Subscription's javadoc

James Roper-2
It is a weak assertion, the word context in this case simply is not a thread or invocation context, but more of an abstract context, the context of a relationship between a particular subscriber that has subscribed to a particular publisher.  As David said, the point is that it's a private matter between a Publisher and Subscriber.  The point of that statement is that if a library were to create a public API like this:

interface SubscriptionFactory {
  Subscription createSubscription();
}

The effect of the returned subscription in that case is undefined according to the reactive streams spec - that is to say it does not make sense to have or use a subscription outside of a Publisher/Subscriber relationship context.

As far as when request() and cancel() can be invoked, the reactive streams spec makes clear that these can be invoked at will by a subscriber, they definitely don't need to be in response to any calls on the subscriber.



On 30 January 2016 at 04:11, Dávid Karnok <[hidden email]> wrote:
I must admit that sounds a bit of a weak guarantee. In RxJava 2 and reactive-streams-commons, Subscription implementations are thread safe and reentrant-safe, thus request and cancel can be called at any time from any thread, even immediately from onSubscribe. What I can deduce, Flow.SubmissionPublisher has also this property.

However, the spec indicates that the link itself is a private matter between Publisher and Subscriber and if you want to expose, for example, cancel() to the outside world in your MySubscriber(), extra care has to be taken inside MySubscriber. Same goes for request(). Here [1][2] is an example of a Subscriber that allows external cancellation and requests.

Bottom line is, that if you can get hold of a Subscription, you won't break the upstream but you may break a downstream if it didn't expect more values you just requested.

-------------

2016-01-29 17:26 GMT+01:00 Pavel Rappo <[hidden email]>:
Hi,

    /**
     * Message control linking a {@link Publisher} and {@link
     * Subscriber}.  Subscribers receive items only when requested,
     * and may cancel at any time. The methods in this interface are
     * intended to be invoked only by their Subscribers; usages in
     * other contexts have undefined effects.
     */
    public static interface Subscription

Could anyone please explain what the "The methods in this interface are intended
to be invoked only by their Subscribers; usages in other contexts have undefined
effects." part is all about? (or 3.1 [1])

I'm sure I understand the relationship between a subscriber and its subscription
to a certain publisher. What I'm not sure about is that I understand what
constitutes the "context" mentioned in the javadoc above.

For example, can a subscriber invoke Subscription.request NOT in a response to
Subscriber.onNext or Subscriber.onSubscribe? Or in the general case, delegate
the responsibility to replenish requests to someone else (e.g. to let
Subscription.request be triggered by outer events)?

Thanks.

--------------------------------------------------------------------------------
[1] https://github.com/reactive-streams/reactive-streams-jvm/#3-subscription-code
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest



--
Best regards,
David Karnok

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest




--
James Roper
Software Engineer

Typesafe – Build reactive apps!
Twitter: @jroper

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Flow.Subscription's javadoc

Viktor Klang


On Sat, Jan 30, 2016 at 6:09 AM, James Roper <[hidden email]> wrote:
It is a weak assertion, the word context in this case simply is not a thread or invocation context, but more of an abstract context, the context of a relationship between a particular subscriber that has subscribed to a particular publisher.  As David said, the point is that it's a private matter between a Publisher and Subscriber.  The point of that statement is that if a library were to create a public API like this:

interface SubscriptionFactory {
  Subscription createSubscription();
}

The effect of the returned subscription in that case is undefined according to the reactive streams spec - that is to say it does not make sense to have or use a subscription outside of a Publisher/Subscriber relationship context.

As far as when request() and cancel() can be invoked, the reactive streams spec makes clear that these can be invoked at will by a subscriber, they definitely don't need to be in response to any calls on the subscriber.

James' correct. I'd also like to add that the reason for the "weak" guarantee is to allow for performant implementations—if a Subscriber chooses to expose its Subscription to some other context/thread/etc, then the Subscriber needs to make sure that the Subscription cannot be used in a way which violates the spec, which means that it may have to wrap the Subscription in a Subscription which provides the stronger guarantees, for instance prevents concurrent signalling etc.

Does that make sense?
 



On 30 January 2016 at 04:11, Dávid Karnok <[hidden email]> wrote:
I must admit that sounds a bit of a weak guarantee. In RxJava 2 and reactive-streams-commons, Subscription implementations are thread safe and reentrant-safe, thus request and cancel can be called at any time from any thread, even immediately from onSubscribe. What I can deduce, Flow.SubmissionPublisher has also this property.

However, the spec indicates that the link itself is a private matter between Publisher and Subscriber and if you want to expose, for example, cancel() to the outside world in your MySubscriber(), extra care has to be taken inside MySubscriber. Same goes for request(). Here [1][2] is an example of a Subscriber that allows external cancellation and requests.

Bottom line is, that if you can get hold of a Subscription, you won't break the upstream but you may break a downstream if it didn't expect more values you just requested.

-------------

2016-01-29 17:26 GMT+01:00 Pavel Rappo <[hidden email]>:
Hi,

    /**
     * Message control linking a {@link Publisher} and {@link
     * Subscriber}.  Subscribers receive items only when requested,
     * and may cancel at any time. The methods in this interface are
     * intended to be invoked only by their Subscribers; usages in
     * other contexts have undefined effects.
     */
    public static interface Subscription

Could anyone please explain what the "The methods in this interface are intended
to be invoked only by their Subscribers; usages in other contexts have undefined
effects." part is all about? (or 3.1 [1])

I'm sure I understand the relationship between a subscriber and its subscription
to a certain publisher. What I'm not sure about is that I understand what
constitutes the "context" mentioned in the javadoc above.

For example, can a subscriber invoke Subscription.request NOT in a response to
Subscriber.onNext or Subscriber.onSubscribe? Or in the general case, delegate
the responsibility to replenish requests to someone else (e.g. to let
Subscription.request be triggered by outer events)?

Thanks.

--------------------------------------------------------------------------------
[1] https://github.com/reactive-streams/reactive-streams-jvm/#3-subscription-code
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest



--
Best regards,
David Karnok

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest




--
James Roper
Software Engineer

Typesafe – Build reactive apps!
Twitter: @jroper

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest




--
Cheers,

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Flow.Subscription's javadoc

Pavel Rappo
On Sun, Jan 31, 2016 at 6:49 PM, Viktor Klang <[hidden email]> wrote:
> Does that make sense?

Yes it does. It's good the excerpt I've referred to in my initial
email doesn't have any connotation beyond what's been explained to me
in this thread. In other words, business as usual: an object should be
interacted with through some interface by anyone who knows and
understands the semantics of that interface. Thanks.
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest