8239584: EventStream::close should state that stream will be stopped

Reviewed-by: mgronlun, mseledtsov

Author: egahlin

src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java

@@ -242,6 +242,10 @@ static EventStream openFile(Path file) throws IOException {
     /**
      * 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 @@ static EventStream openFile(Path file) throws IOException {
      * 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 @@ static EventStream openFile(Path file) throws IOException {
      * 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
      */

src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java

@@ -329,6 +329,32 @@ public void start() {
         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);