improve specification Publisher 1.3

[davidmoten]

As discussed in #431.

[viktorklang]

Thanks @davidmoten! What do you think about the idea that we should take this even further and add serially in the list of definitions, and rephrase the rules which refers to External synchronization?

[davidmoten]

Thanks @davidmoten! What do you think about the idea that we should take this even further and add serially in the list of definitions, and rephrase the rules which refers to External synchronization?

@viktorklang Okey doke, will build on this PR

[viktorklang]

@davidmoten Awesome, thank you!

[davidmoten]

@viktorklang how about this:

For the glossary:

Serial(ly) - In the context of a signal, signals (for example calls to methods on an object) are non-overlapping (non-concurrent). In the context of the JVM, calls to methods on an object are serial if and only if there is a happens-before relationship between those calls.

As mentioned in #431 we also need to:

• remove External Synchronization entry from glossary
• reword Thread-Safety in Glossary
• reword Subscriber 2.7

[viktorklang]

@davidmoten

Thanks David!

I think we can possibly delete the External Synchronization entry in the glossary if we lift bits of it into the Serial(ly) definition, perhaps something along the lines of this:

Serial(ly) - In the context of a Signal[ref glossary], are non-overlapping. In the context of the JVM, calls to methods on an object are serial if and only if there is a happens-before relationship between those calls. This is the case if they are called Synchronously[ref glossary], but when performed asynchronously coordination for Thread Safety[ref glossary] purposes is to be implemented using techniques such as, but not limited to, atomics, monitors, or locks.

As for 2.7, instead of

A Subscriber MUST ensure that all calls on its Subscription take place from the same thread or provide for respective external synchronization.

perhaps we can reword it to be:

A Subscriber MUST ensure that all calls on its Subscription's request and cancel methods are performed serially[ref to glossary].

and for 1.3 instead of:

onSubscribe, onNext, onError and onComplete signaled to a Subscriber MUST be signaled in a thread-safe manner—and if performed by multiple threads—use external synchronization.

it could be reworded to be:

onSubscribe, onNext, onError and onComplete signaled to a Subscriber MUST be signaled serially[ref glossary]

For the other readers: the intent of these changes is not to change anything semantically in the spec.

@reactive-streams/contributors Wdyt?

[davidmoten]

but when performed asynchronously coordination for Thread Safety[ref glossary] purposes is to be implemented using techniques such as, but not limited to, atomics, monitors, or locks.

I'm not keen on this bit, everything that needs to be said is said with more precision with the happens-before statement.

The 2.7 change looks good to me.

The 1.3 change is already in the PR but I'll add the glossary link.

Might be able to remove the use of term Thread Safe from the specs. 2.11 intent is only mention currently:

A Subscriber MUST make sure that all calls on its signal methods happen-before the processing of the respective signals. I.e. the Subscriber must take care of properly publishing the signal to its processing logic.
The intent of this rule is to establish that it is the responsibility of the Subscriber implementation to make sure that asynchronous processing of its signals are thread safe. See JMM definition of Happens-Before in section 17.4.5.

[viktorklang]

@davidmoten Since it is about a glossary entry, I think it is nice to have an explanation that mentions thread satefy. Although happens-before is a good term, I think the added sentence provides more clarity. Or?

@reactive-streams/contributors Thoughts?

[davidmoten]

@viktorklang Perhaps this:

but when performed asynchronously coordination to establish the happens-before relationship is to be implemented using techniques such as, but not limited to, atomics, monitors, or locks.

[viktorklang]

@davidmoten

That might be enough. I took the liberty to insert an extra comma for an in my opinion easier read:

but when performed asynchronously, coordination to establish the happens-before relationship is to be implemented using techniques such as, but not limited to, atomics, monitors, or locks.

[DougLea]

To be pedantic, the happens-before characterization: "calls to methods on an object are serial if and only if there is a happens-before relationship between those calls." should add: "and they are not overlapping"

[viktorklang]

@DougLea That's a great point, I always assume non-overlapping so it is good to spell it out!

[davidmoten]

Thanks @DougLea, I am after precision. The JVM specification talks about happens-before relationships between actions rather than calls. I had assumed that a call (a synchronous method invocation) was equivalent to the action of the method so I'm not sure why to add the extra phrase "and they are not overlapping". Can you clarify?

[DougLea]

@davidmoten The phrase is just intended to validate your assumption, in case there is any doubt.

[davidmoten]

@DougLea beaut, let's include it

[viktorklang]

@davidmoten Let me know when this is ready for review! thank you ^^

[viktorklang]

@davidmoten Ping :)

[davidmoten]

I've updated the PR with results from discussion and clarified things a bit further (I hope).

One thing I wanted to be conscious of in the text was that happens-before helps us out in the single-threaded scenario too by precluding re-entrancy and mutual calls.

For example:

Serial(ly) - In the context of a Signal[ref glossary], are non-overlapping. In the context of the JVM, calls to methods on an object are serial if and only if there is a happens-before relationship between those calls. This is the case if they are called Synchronously ...

That last statement may not apply generally if one methods calls another (so a call to method A also calls method B thus methods A and B overlap). I handle this by omitting the statement.

[viktorklang]

@reactive-streams/contributors Any comments on this before I merge?

[viktorklang]

Thanks @davidmoten!