jdk-sandbox: comparison src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java

equal deleted inserted replaced

-:6f8f18ac1d54
+:7b751fe181a5
 import jdk.jfr.internal.Utils;
 import jdk.jfr.internal.consumer.FileAccess;
 /**
 * 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
+* Creates a stream from the repository of the current Java Virtual Machine
-* Machine (JVM).
+* (JVM).
 * <p>
 * By default, the stream starts with the next event flushed by Flight
 * Recorder.
 *
 * @return an event stream, not {@code null}
 *
 * @param file location of the file, not {@code null}
 *
 * @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
 *         {@code checkRead} method denies read access to the file
 */
 public static EventStream openFile(Path file) throws IOException {
 return new EventFileStream(AccessController.getContext(), file);
 }
 /**
-* 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},
+* @param action an action to perform on each {@code RecordedEvent}, not
-*        not {@code null}
+*        {@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}
+* @param action an action to perform on each {@code RecordedEvent} matching
-*        that matches the event name, not {@code null}
+*        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,
+* @param action an action to perform after the stream has been
-*        not {@code null}
+*        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
+* if an action is not registered, an exception stack trace is printed to
-* trace is printed to standard error.
+* standard error.
 * <p>
-* Adding an error handler overrides the default behavior. If multiple error
+* Registering an action overrides the default behavior. If multiple actions
-* handlers have been added, they will be executed in the order they were
+* have been registered, they are performed in the order of registration.
-* added.
+* <p>
-*
+* If this method itself throws an exception, resulting behavior is
-* @param action an action to be performed if an exception occurs, not
+* undefined.
+*
+* @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,
+* @param action an action to perform after the stream is closed, not
-*        not {@code null}
+*        {@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
+* If the action has been registered multiple times, all instances are
-* removed.
+* 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)
 * @see #onFlush(Runnable)
 * @see #onClose(Runnable)
 */
 boolean remove(Object action);
 /**
 * 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
+* If reuse is set to {@code true), an action should not keep a reference
-* to the event object after the callback from {@code onEvent} has returned.
+* to the event object after the action has completed.
 *
-* @param resuse if event objects can be reused between calls to
+* @param reuse {@code true} if an event object can be reused, {@code false}
-* {@code #onEvent(Consumer)}
+* otherwise
-*
+*/
-*/
+void setReuse(boolean reuse);
-public 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
-*/
-public void setStartTime(Instant startTime);
-/**
-* Specifies end time of the event stream.
-* <p>
-* The end time must be set before the stream is started.
-* <p>
-* When the end time is reached the stream is closed.
-*
-* @param endTime the end time, not {@code null}
-*
-* @throws IllegalStateException if the stream has already been started
-*/
-public void setEndTime(Instant endTime);
-/**
-* Start processing events in the stream.
-* <p>
-* All actions performed on this stream will happen in the current thread.
-*
-* @throws IllegalStateException if the stream is already started or if it
-*         has been closed
-*/
-void start();
-/**
-* Start processing events in the stream asynchronously.
-* <p>
-* All actions on this stream will be performed in a separate thread.
-*
-* @throws IllegalStateException if the stream is already started, or if it
-*         has been closed
-*/
-void startAsync();
-/**
-* Blocks the current thread until the stream is finished, closed, or it
-* times out.
-*
-* @param timeout the maximum time to wait, not {@code null}
-*
-* @throws IllegalArgumentException if timeout is negative
-* @throws InterruptedException
 *
 * @see #start()
 * @see #startAsync()
 */
-void awaitTermination(Duration timeout) throws InterruptedException;
+void setStartTime(Instant startTime);
 /**
-* Blocks the current thread until the stream is finished or closed.
+* Specifies the end time of the stream.
-*
+* <p>
-* @throws InterruptedException
+* The end time must be set before starting the stream.
+* <p>
+* At end time, the stream is closed.
+*
+* @param endTime the end time, not {@code null}
+*
+* @throws IllegalStateException if the stream is already started
 *
 * @see #start()
 * @see #startAsync()
 */
+void setEndTime(Instant endTime);
+/**
+* Start processing of actions.
+* <p>
+* Actions are performed in the current thread.
+*
+* @throws IllegalStateException if the stream is already started or closed
+*/
+void start();
+/**
+* Start asynchronous processing of actions.
+* <p>
+* Actions are performed in a single separate thread.
+*
+* @throws IllegalStateException if the stream is already started or closed
+*/
+void startAsync();
+/**
+* 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 if interrupted while waiting
+*
+* @see #start()
+* @see #startAsync()
+* @see Thread#interrupt()
+*/
+void awaitTermination(Duration timeout) throws InterruptedException;
+/**
+* Blocks until all actions are completed, or the stream is closed, or the
+* current thread is interrupted, whichever happens first.
+*
+* @throws InterruptedException if interrupted while waiting
+*
+* @see #start()
+* @see #startAsync()
+* @see Thread#interrupt()
+*/
 void awaitTermination() throws InterruptedException;
 }

branch	JEP-349-branch
changeset 58129	7b751fe181a5
parent 58020	f082177c5023
child 58145	bc54ed8d908a