Skip to content

Latest commit

 

History

History
390 lines (261 loc) · 22.9 KB

RELEASE-NOTES.md

File metadata and controls

390 lines (261 loc) · 22.9 KB
Raw

Release notes for Reactive Streams

Version 1.0.3 released on 2019-08-23

Announcement:

We—the Reactive Streams community—are pleased to announce the immediate availability of Reactive Streams 1.0.3. This update to Reactive Streams brings the following improvements over 1.0.2.

Highlights:

  • Specification
  • Interfaces
    • No changes
  • Technology Compatibility Kit (TCK)
  • Examples
    • No changes
  • Artifacts
    • FlowAdapters artifact removed, FlowAdapters moved into the core jar (#424)

Specification clarifications 1.0.3

Glossary term "External synchronization" replaced by "Serial(ly)"

1.0.2: Access coordination for thread safety purposes implemented outside of the constructs defined in this specification, using techniques such as, but not limited to, atomics, monitors, or locks.

1.0.3 In the context of a Signal, 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 (implying also that the calls do not overlap). When the calls are 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.

Publisher Rule 3 (Rule and Intent clarified)

1.0.2: 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.

The intent of this rule is to make it clear that external synchronization must be employed if the Publisher intends to send signals from multiple/different threads.

1.0.3: onSubscribe, onNext, onError and onComplete signaled to a Subscriber MUST be signaled serially.

The intent of this rule is to permit the signalling of signals (including from multiple threads) if and only if a happens-before relation between each of the signals is established.

Subscriber Rule 1 (Intent clarified)

1.0.2: A Subscriber MUST signal demand via Subscription.request(long n) to receive onNext signals.

The intent of this rule is to establish that it is the responsibility of the Subscriber to signal when, and how many, elements it is able and willing to receive.

1.0.3: A Subscriber MUST signal demand via Subscription.request(long n) to receive onNext signals.

The intent of this rule is to establish that it is the responsibility of the Subscriber to decide when and how many elements it is able and willing to receive. To avoid signal reordering caused by reentrant Subscription methods, it is strongly RECOMMENDED for synchronous Subscriber implementations to invoke Subscription methods at the very end of any signal processing. It is RECOMMENDED that Subscribers request the upper limit of what they are able to process, as requesting only one element at a time results in an inherently inefficient "stop-and-wait" protocol.

Subscriber Rule 5 (Intent clarified)

1.0.2: A Subscriber MUST call Subscription.cancel() on the given Subscription after an onSubscribe signal if it already has an active Subscription

The intent of this rule is to prevent that two, or more, separate Publishers from thinking that they can interact with the same Subscriber. Enforcing this rule means that resource leaks are prevented since extra Subscriptions will be cancelled.

1.0.3: A Subscriber MUST call Subscription.cancel() on the given Subscription after an onSubscribe signal if it already has an active Subscription

The intent of this rule is to prevent that two, or more, separate Publishers from trying to interact with the same Subscriber. Enforcing this rule means that resource leaks are prevented since extra Subscriptions will be cancelled. Failure to conform to this rule may lead to violations of Publisher rule 1, amongst others. Such violations can lead to hard-to-diagnose bugs.

Subscriber Rule 7 (Rule and Intent clarified)

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

The intent of this rule is to establish that external synchronization must be added if a Subscriber will be using a Subscription concurrently by two or more threads.

1.0.3: A Subscriber MUST ensure that all calls on its Subscription's request and cancel methods are performed serially.

The intent of this rule is to permit the calling of the request and cancel methods (including from multiple threads) if and only if a happens-before relation between each of the calls is established.

TCK alterations 1.0.3

  • PublisherVerification.optional_spec105_emptyStreamMustTerminateBySignallingOnComplete fails if the publisher completes synchronously (#422)
  • IdentityFlowProcessorVerification throws NPE when createFailedFlowPublisher returns null (#425)
  • required_spec208_mustBePreparedToReceiveOnNextSignalsAfterHavingCalledSubscriptionCancel does not wait for request before invoking onNext (#277)
  • Subscriber whitebox verification tests demand (#280)
  • Incomplete documentation on stochastic tests in TCK (#278)
  • TCK performance (#446)
  • TCK: Receptacle#expectError timeout approach (#451)

Contributors

Version 1.0.2 released on 2017-12-19

Announcement:

We—the Reactive Streams community—are pleased to announce the immediate availability of Reactive Streams 1.0.2. This update to Reactive Streams brings the following improvements over 1.0.1.

Highlights:

Specification clarifications 1.0.2

Subscriber Rule 2

1.0.1: The intent of this rule is that a Subscriber should not obstruct the progress of the Publisher from an execution point-of-view. In other words, the Subscriber should not starve the Publisher from CPU cycles.

1.0.2: The intent of this rule is that a Subscriber should not obstruct the progress of the Publisher from an execution point-of-view. In other words, the Subscriber should not starve the Publisher from receiving CPU cycles.

Subscriber Rule 8

1.0.1: The intent of this rule is to highlight that there may be a delay between calling cancel the Publisher seeing that.

1.0.2 The intent of this rule is to highlight that there may be a delay between calling cancel and the Publisher observing that cancellation.

Flow adapters

An adapter library has been created to convert org.reactivestreams to java.util.concurrent.Flow and vice versa. Read more about it here

<dependency>
   <groupId>org.reactivestreams</groupId>
   <artifactId>reactive-streams-flow-adapters</artifactId>
  <version>1.0.2</version>
</dependency>

Flow TCK

A TCK artifact has been created to allow for direct TCK verification of java.util.concurrent.Flow implementations. Read more about it here

<dependency>
   <groupId>org.reactivestreams</groupId>
   <artifactId>reactive-streams-tck-flow</artifactId>
  <version>1.0.2</version>
</dependency>

Automatic Module Name

  • org.reactivestreams:reactive-streams => org.reactivestreams
  • org.reactivestreams:reactive-streams-examples => org.reactivestreams.examples
  • org.reactivestreams:reactive-streams-tck => org.reactivestreams.tck
  • org.reactivestreams:reactive-streams-flow-adapters => org.reactivestreams.flowadapters
  • org.reactivestreams:reactive-streams-tck-flow => org.reactivestreams.tckflow

TCK alterations 1.0.2

  • Added support for Publisher verification of Publishers who do coordinated emission, i.e. where elements only are emitted after all current Subscribers have signalled demand. (#284)
  • The SubscriberWhiteboxVerification has been given more user friendly error messages in the case where the user forgets to call registerOnSubscribe. (#416)[reactive-streams#416]

Contributors

Version 1.0.1 released on 2017-08-09

Announcement:

After more than two years since 1.0.0, we are proud to announce the immediate availability of Reactive Streams version 1.0.1.

Since 1.0.0 was released Reactive Streams has managed to achieve most, if not all, it set out to achieve. There are now numerous implementations, and it is scheduled to be included in JDK9.

Also, most importantly, there are no semantical incompatibilities included in this release.

When JDK9 ships, Reactive Streams will publish a compatibility/conversion library to seamlessly convert between the java.util.concurrent.Flow and the org.reactivestreams namespaces.

Highlights:

  • Specification
    • A new Glossary section
    • Description of the intent behind every single rule
    • No breaking semantical changes
    • Multiple rule clarifications
  • Interfaces
    • No changes
    • Improved JavaDoc
  • Technology Compatibility Kit (TCK)
    • Improved coverage
    • Improved JavaDoc
    • Multiple test alterations

Specification clarifications 1.0.1

Publisher Rule 1

1.0.0: The total number of onNext signals sent by a Publisher to a Subscriber MUST be less than or equal to the total number of elements requested by that Subscriber´s Subscription at all times.

1.0.1: The total number of onNext´s signalled by a Publisher to a Subscriber MUST be less than or equal to the total number of elements requested by that Subscriber´s Subscription at all times.

Comment: Minor spelling update.

Publisher Rule 2

1.0.0: A Publisher MAY signal less onNext than requested and terminate the Subscription by calling onComplete or onError.

1.0.1: A Publisher MAY signal fewer onNext than requested and terminate the Subscription by calling onComplete or onError.

Comment: Minor spelling update.

Publisher Rule 3

1.0.0: onSubscribe, onNext, onError and onComplete signaled to a Subscriber MUST be signaled sequentially (no concurrent notifications).

1.0.1: 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.

Comment: Reworded the part about sequential signal and its implications, for clarity.

Subscriber Rule 6

1.0.0: A Subscriber MUST call Subscription.cancel() if it is no longer valid to the Publisher without the Publisher having signaled onError or onComplete.

1.0.1: A Subscriber MUST call Subscription.cancel() if the Subscription is no longer needed.

Comment: Rule could be reworded since it now has an intent section describing desired effect.

Subscriber Rule 11

1.0.0: A Subscriber MUST make sure that all calls on its onXXX methods happen-before [1] the processing of the respective signals. I.e. the Subscriber must take care of properly publishing the signal to its processing logic.

1.0.1: 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.

Comment: Rule slightly reworded to use the glossary for signal instead of the more ad-hoc name "onXXX methods". Footnote was reworked into the Intent-section of the rule.

Subscription Rule 1

1.0.0: Subscription.request and Subscription.cancel MUST only be called inside of its Subscriber context. A Subscription represents the unique relationship between a Subscriber and a Publisher [see 2.12].

1.0.1: Subscription.request and Subscription.cancel MUST only be called inside of its Subscriber context.

Comment: Second part of rule moved into the Intent-section of the rule.

Subscription Rule 3

1.0.0: Subscription.request MUST place an upper bound on possible synchronous recursion between Publisher and Subscriber[1].

1.0.1: Subscription.request MUST place an upper bound on possible synchronous recursion between Publisher and Subscriber.

Comment: Footnote reworked into the Intent-section of the rule.

Subscription Rule 4

1.0.0: Subscription.request SHOULD respect the responsivity of its caller by returning in a timely manner[2].

1.0.1: Subscription.request SHOULD respect the responsivity of its caller by returning in a timely manner.

Comment: Footnote reworked into the Intent-section of the rule.

Subscription Rule 5

1.0.0: Subscription.cancel MUST respect the responsivity of its caller by returning in a timely manner[2], MUST be idempotent and MUST be thread-safe.

1.0.1: Subscription.cancel MUST respect the responsivity of its caller by returning in a timely manner, MUST be idempotent and MUST be thread-safe.

Comment: Footnote reworked into the Intent-section of the rule.

Subscription Rule 9

1.0.0: While the Subscription is not cancelled, Subscription.request(long n) MUST signal onError with a java.lang.IllegalArgumentException if the argument is <= 0. The cause message MUST include a reference to this rule and/or quote the full rule.

1.0.1: While the Subscription is not cancelled, Subscription.request(long n) MUST signal onError with a java.lang.IllegalArgumentException if the argument is <= 0. The cause message SHOULD explain that non-positive request signals are illegal.

Comment: The MUST requirement to include a reference to the rule in the exception message has been dropped, in favor of that the exception message SHOULD explain that non-positive requests are illegal.

Subscription Rule 13

1.0.0: While the Subscription is not cancelled, Subscription.cancel() MUST request the Publisher to eventually drop any references to the corresponding subscriber. Re-subscribing with the same Subscriber object is discouraged [see 2.12], but this specification does not mandate that it is disallowed since that would mean having to store previously cancelled subscriptions indefinitely.

1.0.1: While the Subscription is not cancelled, Subscription.cancel() MUST request the Publisher to eventually drop any references to the corresponding subscriber.

Comment: Second part of rule reworked into the Intent-section of the rule.

Subscription Rule 15

1.0.0: Calling Subscription.cancel MUST return normally. The only legal way to signal failure to a Subscriber is via the onError method.

1.0.1: Calling Subscription.cancel MUST return normally.

Comment: Replaced second part of rule with a definition for return normally in the glossary.

Subscription Rule 16

1.0.0: Calling Subscription.request MUST return normally. The only legal way to signal failure to a Subscriber is via the onError method.

1.0.1: Calling Subscription.request MUST return normally.

Comment: Replaced second part of rule with a definition for return normally in the glossary.

Subscription Rule 17

1.0.0: A Subscription MUST support an unbounded number of calls to request and MUST support a demand (sum requested - sum delivered) up to 2^63-1 (java.lang.Long.MAX_VALUE). A demand equal or greater than 2^63-1 (java.lang.Long.MAX_VALUE) MAY be considered by the Publisher as “effectively unbounded”[3].

1.0.1: A Subscription MUST support an unbounded number of calls to request and MUST support a demand up to 2^63-1 (java.lang.Long.MAX_VALUE). A demand equal or greater than 2^63-1 (java.lang.Long.MAX_VALUE) MAY be considered by the Publisher as “effectively unbounded”.

Comment: Rule simplified by defining demand in the glossary, and footnote was reworked into the Intent-section of the rule.

TCK alterations 1.0.1

  • Fixed potential resource leaks in partially consuming Publisher tests (#375)
  • Fixed potential resource leaks in partially emitting Subscriber tests (#372, #373)
  • Renamed untested_spec305_cancelMustNotSynchronouslyPerformHeavyCompuatation to untested_spec305_cancelMustNotSynchronouslyPerformHeavyComputation (#306)
  • Allow configuring separate timeout for "no events during N time", allowing for more aggressive timeouts in the rest of the test suite if required (#314)
  • New test verifying Rule 2.10, in which subscriber must be prepared to receive onError signal without having signaled request before (#374)
  • The verification of Rule 3.9 has been split up into 2 different tests, one to verify that an IllegalArgumentException is sent, and the other an optional check to verify that the exception message informs that non-positive request signals are illegal.

Contributors