Repository: apache/flink
File: flink-core/src/main/java/org/apache/flink/api/common/operators/MailboxExecutor.java (Java)

Code before:
public interface MailboxExecutor {
    /** A constant for empty args to save on object allocation. */
    Object[] EMPTY_ARGS = new Object[0];

    /** Extra options to configure enqueued mails. */
    @PublicEvolving
    interface MailOptions {
        static MailOptions options() {
            return MailOptionsImpl.DEFAULT;
        }

        boolean isHighPriority();

        /**
         * Mark this mail as deferrable.
         *
         * <p>Runtime can decide to defer execution of deferrable mails. For example, to unblock
         * subtask thread as quickly as possible, deferrable mails are not executed during {@link
         * #yield()} or {@link #tryYield()}. This is done to speed up checkpointing, by skipping
         * execution of potentially long-running mails.
         */
        static MailOptions deferrable() {
            return MailOptionsImpl.DEFERRABLE;
        }

        static MailOptions highPriority() {
            return MailOptionsImpl.HIGH_PRIORITY;
        }
    }

    /**
     * Executes the given command at some time in the future in the mailbox thread.
     *
     * <p>An optional description can (and should) be added to ease debugging and error-reporting.
     * The description may contain placeholder that refer to the provided description arguments
     * using {@link java.util.Formatter} syntax. The actual description is only formatted on demand.
     *
     * @param command the runnable task to add to the mailbox for execution.
     * @param description the optional description for the command that is used for debugging and
     *     error-reporting.
     * @throws RejectedExecutionException if this task cannot be accepted for execution, e.g.
     *     because the mailbox is quiesced or closed.
     */
    default void execute(ThrowingRunnable<? extends Exception> command, String description) {
        execute(command, description, EMPTY_ARGS);
    }

    /**
     * Executes the given command at some time in the future in the mailbox thread.
     *
     * <p>An optional description can (and should) be added to ease debugging and error-reporting.

Review comment (suggestion):
Could we add a docstring here explaining new public interface methods? (also for `isHighPriority`)

Code after:
public interface MailboxExecutor {
    /** A constant for empty args to save on object allocation. */
    Object[] EMPTY_ARGS = new Object[0];

    /** Extra options to configure enqueued mails. */
    @PublicEvolving
    interface MailOptions {

        /**
         * Runtime can decide to defer execution of deferrable mails. For example, to unblock
         * subtask thread as quickly as possible, deferrable mails are not executed during {@link
         * #yield()} or {@link #tryYield()}. This is done to speed up checkpointing, by skipping
         * execution of potentially long-running mails.
         */
        boolean isDeferrable();

        /**
         * The urgent mail will be executed first compared to other mails. For example, handling
         * unaligned checkpoint barrier or some control mails are expected to be executed as soon as
         * possible.
         */
        boolean isUrgent();

        static MailOptions options() {
            return MailOptionsImpl.DEFAULT;
        }

        /** Mark this mail as deferrable. */
        static MailOptions deferrable() {
            return MailOptionsImpl.DEFERRABLE;
        }

        /** Mark this mail as urgent. */
        static MailOptions urgent() {
            return MailOptionsImpl.URGENT;
        }
    }

    /**
     * Executes the given command at some time in the future in the mailbox thread.
     *
     * <p>An optional description can (and should) be added to ease debugging and error-reporting.
     * The description may contain placeholder that refer to the provided description arguments
     * using {@link java.util.Formatter} syntax. The actual description is only formatted on demand.
     *
     * @param command the runnable task to add to the mailbox for execution.
     * @param description the optional description for the command that is used for debugging and
     *     error-reporting.
     * @throws RejectedExecutionException if this task cannot be accepted for execution, e.g.
     *     because the mailbox is quiesced or closed.
     */