Package 

Interface StreamSerialProcessingQueue


  • 
    public interface StreamSerialProcessingQueue
    
                        

    A simple serial execution queue for suspending tasks.

    Implementations guarantee that submitted jobs are executed one-by-one in the order they were accepted (FIFO), never concurrently. This is useful for protecting critical sections, enforcing request ordering, or simplifying stateful operations that are not thread-safe when run in parallel.

    • Serialization: Only one job runs at a time.

    • Ordering: Jobs are executed in the order they are successfully submitted.

    • Result delivery: The return value is wrapped in Result; failures are surfaced as Result.failure rather than throwing.

    • Backpressure: If the queue is full (implementation-defined capacity), submit will suspend until space is available or the queue is stopped.

    • Stop behavior: Calling stop makes the queue unavailable for further submissions and cancels the currently running job (if any). Any jobs that are queued but not yet started are failed.

    • Cancelling the caller of submit only cancels the suspension while waiting for the result; the job may still run if it was already accepted by the queue (implementation-specific). Call stop to cancel/flush work at the queue level.

    • Method Summary

      Modifier and Type Method Description
      abstract <T extends Any> Result<T> submit(SuspendFunction0<T> job) Submits a suspending job for serialized execution.
      abstract Result<Unit> start() Starts the processor if it's not already running.
      abstract Result<Unit> stop(Long timeout) Stops the processor and fails outstanding work.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • submit

         abstract <T extends Any> Result<T> submit(SuspendFunction0<T> job)

        Submits a suspending job for serialized execution.

        If the processor is not running, it will be started automatically by the implementation. The job will run exclusively (no other jobs run in parallel) and in FIFO order relative to other accepted jobs.

        Parameters:
        job - The suspending block to execute on the queue's worker.
      • start

         abstract Result<Unit> start()

        Starts the processor if it's not already running.

      • stop

         abstract Result<Unit> stop(Long timeout)

        Stops the processor and fails outstanding work.

        After calling this:

        • No new jobs are accepted (subsequent submit calls should fail fast).

        • The currently running job (if any) is cancelled and completed with failure.

        • All queued but not yet started jobs are completed with failure.

        • The queue is not reusable unless the implementation documents otherwise.

        Parameters:
        timeout - The maximum time to wait for the running job to complete before hard-cancelling the processor.