--- a/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java Thu Sep 12 20:46:55 2019 -0700
+++ b/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java Fri Sep 13 18:46:07 2019 +0200
@@ -40,12 +40,60 @@
/**
* Represents a stream of events.
+ * <p>
+ * A stream is a sequence of events and the way to interact with a stream is to
+ * register actions.
+ * <p>
+ * To receive a notification when an event arrives, register an action using the
+ * {@link #onEvent(Consumer)} method. To filter the stream for an event with a
+ * specific name, use {@link #onEvent(String, Consumer)} method.
+ *
+ * By default, the same {@code RecordedEvent} object can be used for
+ * representing two or more distinct events. The object can be delivered
+ * multiple times to the same action as well as to other actions. If the life
+ * cycle of the event object is needed outside the scope of an action, the
+ * {@link #setReuse(boolean)} method should be set to {@code false} so that a
+ * new object is allocated for each event.
+ *
+ * <p>
+ * Events are delivered in batches. To receive a notification when a batch is
+ * complete, register an action using the {@link #onFlush(Runnable)} method.
+ * This is an opportunity to aggregate or push data to external systems while
+ * the Java Virtual Machine (JVM) is preparing the next batch.
+ * <p>
+ * Events within a batch are sorted chronologically by their end time. If
+ * ordering is not a concern, sorting can be disabled using the
+ * {@link #setOrdered(boolean)} method.
+ * <p>
+ * To dispatch events to registered actions, the stream must be started. To
+ * start processing in the current thread, invoke the {@link #start()} method.
+ * To process actions asynchronously in a separate thread, invoke the
+ * {@link #startAsync()} method. To await completion of the stream, use the
+ * awaitTermination {@link #awaitTermination()} or the {link
+ * {@link #awaitTermination(Duration)} method.
+ * <p>
+ * When a stream ends it is automatically closed. To manually stop processing of
+ * events, close the stream with the {@link #close()} method. A stream can also
+ * be automatically closed in exceptional circumstances, for instance if the JVM
+ * exits. To receive a notification in any of these occasions, use the
+ * {@link #onClose(Runnable)} method to register an action.
+ * <p>
+ * If an unexpected exception occurs in an action, it is possible to catch the
+ * exception in an error handler. An error handler can be registered using the
+ * {@link #onError(Runnable)} method. If no error handler is registered, the
+ * default behavior is to print the exception and its backtrace to the standard
+ * error stream.
+ * <p>
+ * The following example demonstrates how an {@code EventStream} can be used to
+ * listen to garbage collection and CPU Load events
+ * <p>
+ *
*/
public interface EventStream extends AutoCloseable {
/**
- * Creates a stream from the disk repository of the current Java Virtual
- * Machine (JVM).
+ * Creates a stream from the repository of the current Java Virtual Machine
+ * (JVM).
* <p>
* By default, the stream starts with the next event flushed by Flight
* Recorder.
@@ -96,7 +144,7 @@
*
* @return an event stream, not {@code null}
*
- * @throws IOException if a stream can't be opened, or an I/O error occurs
+ * @throws IOException if the file can't be opened, or an I/O error occurs
* during reading
*
* @throws SecurityException if a security manager exists and its
@@ -107,71 +155,75 @@
}
/**
- * Performs an action on all events in the stream.
+ * Registers an action to perform on all events in the stream.
*
- * @param action an action to be performed on each {@code RecordedEvent},
- * not {@code null}
+ * @param action an action to perform on each {@code RecordedEvent}, not
+ * {@code null}
*/
void onEvent(Consumer<RecordedEvent> action);
/**
- * Performs an action on all events in the stream with a specified name.
+ * Registers an action to perform on all events matching a name.
*
* @param eventName the name of the event, not {@code null}
*
- * @param action an action to be performed on each {@code RecordedEvent}
- * that matches the event name, not {@code null}
+ * @param action an action to perform on each {@code RecordedEvent} matching
+ * the event name, not {@code null}
*/
void onEvent(String eventName, Consumer<RecordedEvent> action);
/**
- * Performs an action when the event stream has been flushed.
+ * Registers an action to perform after the stream has been flushed.
*
- * @param action an action to be performed after stream has been flushed,
- * not {@code null}
+ * @param action an action to perform after the stream has been
+ * flushed, not {@code null}
*/
void onFlush(Runnable action);
/**
- * Performs an action if an exception occurs when processing the stream.
+ * Registers an action to perform if an exception occurs.
* <p>
- * if an error handler has not been added to the stream, an exception stack
- * trace is printed to standard error.
+ * if an action is not registered, an exception stack trace is printed to
+ * standard error.
* <p>
- * Adding an error handler overrides the default behavior. If multiple error
- * handlers have been added, they will be executed in the order they were
- * added.
+ * Registering an action overrides the default behavior. If multiple actions
+ * have been registered, they are performed in the order of registration.
+ * <p>
+ * If this method itself throws an exception, resulting behavior is
+ * undefined.
*
- * @param action an action to be performed if an exception occurs, not
+ * @param action an action to perform if an exception occurs, not
* {@code null}
*/
void onError(Consumer<Throwable> action);
/**
- * Performs an action when the event stream is closed.
+ * Registers an action to perform when the stream is closed.
* <p>
- * If the stream is already closed, the action will be executed immediately
+ * If the stream is already closed, the action will be performed immediately
* in the current thread.
*
- * @param action an action to be performed after the stream has been closed,
- * not {@code null}
+ * @param action an action to perform after the stream is closed, not
+ * {@code null}
+ * @see #close()
*/
void onClose(Runnable action);
/**
- * Releases all resources associated with this event stream.
+ * Releases all resources associated with this stream.
*/
void close();
/**
- * Removes an action from the stream.
+ * Unregisters an action.
* <p>
- * If the action has been added multiple times, all instance of it will be
- * removed.
+ * If the action has been registered multiple times, all instances are
+ * unregistered.
*
- * @param action the action to remove, not {@code null}
+ * @param action the action to unregister, not {@code null}
*
- * @return {@code true} if the action was removed, {@code false} otherwise
+ * @return {@code true} if the action was unregistered, {@code false}
+ * otherwise
*
* @see #onEvent(Consumer)
* @see #onEvent(String, Consumer)
@@ -183,91 +235,98 @@
/**
* Specifies that the event object in an {@link #onEvent(Consumer)} action
- * is to be reused.
+ * can be reused.
* <p>
- * If reuse is set to {@code true), a callback should not keep a reference
- * to the event object after the callback from {@code onEvent} has returned.
+ * If reuse is set to {@code true), an action should not keep a reference
+ * to the event object after the action has completed.
*
- * @param resuse if event objects can be reused between calls to
- * {@code #onEvent(Consumer)}
- *
+ * @param reuse {@code true} if an event object can be reused, {@code false}
+ * otherwise
*/
- public void setReuse(boolean reuse);
+ void setReuse(boolean reuse);
/**
* Specifies that events arrives in chronological order, sorted by the time
- * they were committed to the event stream.
+ * they were committed to the stream.
*
* @param ordered if event objects arrive in chronological order to
* {@code #onEvent(Consumer)}
*/
- public void setOrdered(boolean ordered);
+ void setOrdered(boolean ordered);
/**
- * Specifies start time of the event stream.
+ * Specifies the start time of the stream.
* <p>
- * The start time must be set before the stream is started.
+ * The start time must be set before starting the stream
*
* @param startTime the start time, not {@code null}
*
- * @throws IllegalStateException if the stream has already been started
+ * @throws IllegalStateException if the stream is already started
+ *
+ * @see #start()
+ * @see #startAsync()
*/
- public void setStartTime(Instant startTime);
+ void setStartTime(Instant startTime);
/**
- * Specifies end time of the event stream.
+ * Specifies the end time of the stream.
* <p>
- * The end time must be set before the stream is started.
+ * The end time must be set before starting the stream.
* <p>
- * When the end time is reached the stream is closed.
+ * At end time, the stream is closed.
*
* @param endTime the end time, not {@code null}
*
- * @throws IllegalStateException if the stream has already been started
+ * @throws IllegalStateException if the stream is already started
+ *
+ * @see #start()
+ * @see #startAsync()
*/
- public void setEndTime(Instant endTime);
+ void setEndTime(Instant endTime);
/**
- * Start processing events in the stream.
+ * Start processing of actions.
* <p>
- * All actions performed on this stream will happen in the current thread.
+ * Actions are performed in the current thread.
*
- * @throws IllegalStateException if the stream is already started or if it
- * has been closed
+ * @throws IllegalStateException if the stream is already started or closed
*/
void start();
/**
- * Start processing events in the stream asynchronously.
+ * Start asynchronous processing of actions.
* <p>
- * All actions on this stream will be performed in a separate thread.
+ * Actions are performed in a single separate thread.
*
- * @throws IllegalStateException if the stream is already started, or if it
- * has been closed
+ * @throws IllegalStateException if the stream is already started or closed
*/
void startAsync();
/**
- * Blocks the current thread until the stream is finished, closed, or it
- * times out.
+ * Blocks until all actions are completed, or the stream is closed, or the
+ * timeout occurs, or the current thread is interrupted, whichever happens
+ * first.
*
* @param timeout the maximum time to wait, not {@code null}
*
* @throws IllegalArgumentException if timeout is negative
- * @throws InterruptedException
+ * @throws InterruptedException if interrupted while waiting
*
* @see #start()
* @see #startAsync()
+ * @see Thread#interrupt()
*/
void awaitTermination(Duration timeout) throws InterruptedException;
/**
- * Blocks the current thread until the stream is finished or closed.
+ * Blocks until all actions are completed, or the stream is closed, or the
+ * current thread is interrupted, whichever happens first.
*
- * @throws InterruptedException
+ * @throws InterruptedException if interrupted while waiting
*
* @see #start()
* @see #startAsync()
+ * @see Thread#interrupt()
*/
void awaitTermination() throws InterruptedException;
}
\ No newline at end of file