Summary

Update javadoc for jdk.jfr.EventStream and jdk.jfr.RecordingStream to make it clear that a stream is stopped when the closed method is invoked

Problem

First time users of the the EventStream APi.have been surprised that they don't get events. What they typically do is write code like this:

 try (var rs = new RecordingStream()) {
    es.enable("jdk.CPULoad");
    es.onEvent("jdk.CPULoad", System.out::println);
    es.startAsync();
 } 

When the try-with-resources block exits, the stream is stopped and they don't get any events.

Solution

Update the javadoc for EventStream and RecordingStream so the contract is made more clear and also add small code sample to the RecordingStream::startAsync method.

Specification

diff --git a/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java b/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java
--- a/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java
+++ b/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java
@@ -242,6 +242,10 @@
     /**
      * Releases all resources associated with this stream.
      * <p>
+     * If a stream is started, asynchronously or synchronously, it is stopped
+     * immediately or after the next flush. This method does <em>NOT</em>
+     * guarantee that all registered actions are completed before return.
+     * <p>
      * Closing a previously closed stream has no effect.
      */
     void close();
@@ -320,6 +324,8 @@
      * Start processing of actions.
      * <p>
      * Actions are performed in the current thread.
+     * <p>
+     * To stop the stream, use the {@code #close()} method.
      *
      * @throws IllegalStateException if the stream is already started or closed
      */
@@ -329,6 +335,8 @@
      * Start asynchronous processing of actions.
      * <p>
      * Actions are performed in a single separate thread.
+     * <p>
+     * To stop the stream, use the {@code #close()} method.
      *
      * @throws IllegalStateException if the stream is already started or closed
      */
diff --git a/src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java b/src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java
--- a/src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java
+++ b/src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java
@@ -329,6 +329,32 @@
         directoryStream.start(startNanos);
     }

+    /**
+     * Start asynchronous processing of actions.
+     * <p>
+     * Actions are performed in a single separate thread.
+     * <p>
+     * To stop the stream, use the {@code #close()} method.
+     * <p>
+     * The following example prints the CPU usage for ten seconds. When
+     * the current thread leaves the try-with-resources block the
+     * stream is stopped/closed.
+     * <pre>
+     * <code>
+     * try (var stream = new RecordingStream()) {
+     *   stream.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
+     *   stream.onEvent("jdk.CPULoad", event -> {
+     *     System.out.println(event);
+     *   });
+     *   stream.startAsync();
+     *   Thread.sleep(10_000);
+     * }
+     * </code>
+     * </pre>
+     *
+     * @throws IllegalStateException if the stream is already started or closed
+     *
+     */
     @Override
     public void startAsync() {
         PlatformRecording pr = PrivateAccess.getInstance().getPlatformRecording(recording);