Interface WorkloadScheduler

All Superinterfaces:
AutoCloseable
public interface WorkloadScheduler extends AutoCloseable
Transport-neutral task scheduling, execution and lease-ownership API.

Implementations must be thread-safe. The baseline API intentionally does not require durable storage, consensus, distributed transactions, or exactly-once execution. Authorization, resource policy, overload, and audit behavior are implementation responsibilities.

  • Method Details

    • schedulerId

      String schedulerId()
      Returns the scheduler id.
      Returns:
      scheduler id

    • submit

      WorkloadHandle submit(TaskSubmission submission)
      Submits a task.
      Parameters:
      submission - submission request
      Returns:
      task handle

    • acquireLease

      TaskLease acquireLease(TaskId taskId, LeaseOwner owner, Duration duration)
      Acquires task ownership under a new fencing generation.

      A live lease held by another owner can prevent acquisition. A granted lease identifies the owner and expiry; it does not itself fence an external database or establish durable recovery. Those guarantees belong to the implementation.

      Parameters:
      taskId - task id
      owner - lease owner
      duration - requested lease lifetime; null selects the implementation default
      Returns:
      new lease

    • renewLease

      TaskLease renewLease(TaskId taskId, LeaseOwner owner, FencingToken token, Duration duration)
      Extends an existing live lease while retaining its fencing generation.

      The owner and token must match current authority. Renewal must not revive an expired or superseded owner; obtain fresh authority after ownership loss.

      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token supplied by owner
      duration - renewed lifetime measured from renewal; null selects the implementation default
      Returns:
      renewed lease

    • releaseLease

      void releaseLease(TaskId taskId, LeaseOwner owner, FencingToken token)
      Releases a live lease.
      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token

    • reportProgress

      void reportProgress(TaskId taskId, LeaseOwner owner, FencingToken token, TaskProgress progress)
      Reports task progress.
      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token
      progress - progress snapshot

    • checkpoint

      TaskCheckpoint checkpoint(TaskId taskId, LeaseOwner owner, FencingToken token, Map<String,String> metadata)
      Records explicit recoverable task metadata under current lease authority.

      This is an application safe point, not a serialized Java stack. The implementation determines storage durability, retention, metadata limits and redaction. A stale owner must not replace the current checkpoint.

      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token
      metadata - checkpoint metadata
      Returns:
      checkpoint snapshot

    • complete

      void complete(TaskId taskId, LeaseOwner owner, FencingToken token, Object result)
      Publishes the task result under current lease authority and selects terminal completion.

      Result size/type limits belong to the scheduler profile. Completion is not atomic with unrelated external effects. A cancelled or timed-out caller does not establish that physical work has stopped or that this result was absent.

      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token
      result - result value

    • fail

      void fail(TaskId taskId, LeaseOwner owner, FencingToken token, TaskFailure failure)
      Fails a task.
      Parameters:
      taskId - task id
      owner - lease owner
      token - fencing token
      failure - failure descriptor

    • cancel

      void cancel(TaskId taskId)
      Requests cancellation.
      Parameters:
      taskId - task id

    • status

      TaskStatus status(TaskId taskId)
      Returns current task status.
      Parameters:
      taskId - task id
      Returns:
      status snapshot

    • listTasks

      List<TaskStatus> listTasks()
      Lists local task status snapshots.
      Returns:
      local statuses

    • submitAsync

      AsyncResult<Object> submitAsync(TaskSubmission submission, WorkloadExecutor executor)
      Executes a task asynchronously.
      Parameters:
      submission - submission request
      executor - executor
      Returns:
      future-like result

    • submitOneWay

      TaskRef submitOneWay(TaskSubmission submission, WorkloadExecutor executor)
      Enqueues a one-way task and returns after local acceptance.
      Parameters:
      submission - submission request
      executor - executor
      Returns:
      task reference

    • stream

      <T> StreamHandle<T> stream(TaskSubmission submission, StreamProducer<T> producer)
      Starts a bounded server-style stream.
      Type Parameters:
      T - item type
      Parameters:
      submission - submission request
      producer - producer callback
      Returns:
      stream handle

    • fanOut

      FanOutResult fanOut(FanOutRequest request, CandidateInvoker invoker)
      Invokes a function over fan-out candidates.
      Parameters:
      request - request
      invoker - per-candidate invoker
      Returns:
      fan-out result

    • scatterGather

      ScatterGatherResult scatterGather(ScatterGatherRequest request, CandidateInvoker invoker)
      Invokes a function over scatter-gather candidates.
      Parameters:
      request - request
      invoker - per-candidate invoker
      Returns:
      scatter-gather result

    • close

      void close()
      Specified by:
      close in interface AutoCloseable