Trait ExecutorService 

pub trait ExecutorService: Send + Sync {
    type ResultHandle<R, E>: TaskResultHandle<R, E>
       where R: Send + 'static,
             E: Send + 'static;
    type TrackedHandle<R, E>: TrackedTaskHandle<R, E>
       where R: Send + 'static,
             E: Send + 'static;

    // Required methods
    fn submit<T, E>(&self, task: T) -> Result<(), SubmissionError>
       where T: Runnable<E> + Send + 'static,
             E: Send + 'static;
    fn submit_callable<C, R, E>(
        &self,
        task: C,
    ) -> Result<Self::ResultHandle<R, E>, SubmissionError>
       where C: Callable<R, E> + Send + 'static,
             R: Send + 'static,
             E: Send + 'static;
    fn submit_tracked_callable<C, R, E>(
        &self,
        task: C,
    ) -> Result<Self::TrackedHandle<R, E>, SubmissionError>
       where C: Callable<R, E> + Send + 'static,
             R: Send + 'static,
             E: Send + 'static;
    fn shutdown(&self);
    fn stop(&self) -> StopReport;
    fn lifecycle(&self) -> ExecutorServiceLifecycle;
    fn wait_termination(&self);

    // Provided methods
    fn submit_tracked<T, E>(
        &self,
        task: T,
    ) -> Result<Self::TrackedHandle<(), E>, SubmissionError>
       where T: Runnable<E> + Send + 'static,
             E: Send + 'static { ... }
    fn is_running(&self) -> bool { ... }
    fn is_shutting_down(&self) -> bool { ... }
    fn is_stopping(&self) -> bool { ... }
    fn is_not_running(&self) -> bool { ... }
    fn is_terminated(&self) -> bool { ... }
}

Managed task service with submission and lifecycle control.

ExecutorService is intentionally separate from Executor. An executor describes an execution strategy; an executor service accepts tasks into a managed service that may queue, schedule, assign workers, and track lifecycle.

submit and submit_callable return Result values whose outer Ok means only that the service accepted the task. It does not mean the task has started or succeeded. submit is fire-and-forget; callable and tracked variants return handles for observing the final task result.

Lifecycle

A service starts in ExecutorServiceLifecycle::Running. While running, submissions may be accepted. Calling shutdown starts an orderly shutdown and moves the service toward ExecutorServiceLifecycle::ShuttingDown: later submissions are rejected, while work accepted before shutdown is allowed to finish normally. Calling stop starts an abrupt stop and moves the service toward ExecutorServiceLifecycle::Stopping: later submissions are rejected and the implementation attempts to cancel or abort accepted work that can still be stopped.

shutdown and stop are both terminal admission decisions; neither allows the service to become running again. The difference is how accepted work is treated. shutdown preserves accepted work, including queued or scheduled work, unless a concrete service documents a stronger policy. stop is a best-effort interruption request for queued, scheduled, unstarted, or runtime-abortable work. Work already running in ordinary Rust code, blocking calls, or OS threads may not be forcibly interrupted, so termination can still wait for that work to return.

A service reaches ExecutorServiceLifecycle::Terminated after shutdown or stop has been requested and no accepted work remains active. Accepted work may have completed normally, failed, panicked, been cancelled, or been dropped by its runner endpoint, or been aborted according to the concrete service’s capabilities.

Required Associated Types

type ResultHandle<R, E>: TaskResultHandle<R, E> where R: Send + 'static, E: Send + 'static

Result handle returned for an accepted callable task.

type TrackedHandle<R, E>: TrackedTaskHandle<R, E> where R: Send + 'static, E: Send + 'static

Tracked handle returned for accepted tasks that expose status.

Required Methods

fn submit<T, E>(&self, task: T) -> Result<(), SubmissionError>

where T: Runnable<E> + Send + 'static, E: Send + 'static,

Submits a runnable task to this service.

Parameters

• task - A fallible background action with no business return value.

Returns

Ok(()) if the service accepts the task. This only reports acceptance; it does not report task start or task success. Returns Err(SubmissionError) if the service refuses the task before accepting it.

Errors

Returns SubmissionError when the service refuses the task before accepting it.

fn submit_callable<C, R, E>( &self, task: C, ) -> Result<Self::ResultHandle<R, E>, SubmissionError>

where C: Callable<R, E> + Send + 'static, R: Send + 'static, E: Send + 'static,

Submits a callable task to this service.

Parameters

• task - A fallible computation whose success value should be captured in the returned handle.

Returns

Ok(handle) if the service accepts the task. This only reports acceptance; task success, task failure, panic, or cancellation must be observed through the returned handle. Returns Err(SubmissionError) if the service refuses the task before accepting it.

Errors

Returns SubmissionError when the service refuses the task before accepting it.

fn submit_tracked_callable<C, R, E>( &self, task: C, ) -> Result<Self::TrackedHandle<R, E>, SubmissionError>

where C: Callable<R, E> + Send + 'static, R: Send + 'static, E: Send + 'static,

Submits a callable task and returns a tracked handle.

Parameters

• task - A fallible computation whose success value should be captured in the returned handle.

Returns

Ok(handle) if the service accepts the task. The handle exposes status, pre-start cancellation, and final result retrieval.

Errors

Returns SubmissionError when the service refuses the task before accepting it.

fn shutdown(&self)

Initiates an orderly shutdown.

After shutdown starts, the service rejects new submissions and enters the ExecutorServiceLifecycle::ShuttingDown path. Already accepted work is allowed to complete normally, including work that is queued, scheduled, or running, unless the concrete service documents a stronger cancellation policy.

This method is an admission gate change, not a wait operation. Use wait_termination to block until all accepted work has completed or the service has otherwise terminated.

fn stop(&self) -> StopReport

Attempts to stop accepting new tasks and stop accepted work immediately.

After stop starts, the service rejects new submissions and enters the ExecutorServiceLifecycle::Stopping path. The implementation should cancel queued, scheduled, or unstarted work where possible, and abort runtime-managed work where its runtime provides an abort mechanism.

stop is best effort. It cannot promise to interrupt arbitrary Rust code, blocking calls, or already-running OS-thread work. Such work may continue until it returns, and service termination waits for any non-interruptible accepted work that remains active.

Returns

A count-based stop report describing queued, running, and cancelled work observed while handling the request.

fn lifecycle(&self) -> ExecutorServiceLifecycle

Returns the current lifecycle state.

Returns

The lifecycle state currently observed by this service.

fn wait_termination(&self)

Blocks the current thread until the service has terminated.

This method is a synchronous, blocking wait. It returns only after shutdown or stop has been requested and no accepted tasks remain active. If it is called while the service is still ExecutorServiceLifecycle::Running and no other thread requests shutdown or stop, it may block forever.

Implementations must not present this method as an asynchronous or non-blocking operation.

Provided Methods

fn submit_tracked<T, E>( &self, task: T, ) -> Result<Self::TrackedHandle<(), E>, SubmissionError>

where T: Runnable<E> + Send + 'static, E: Send + 'static,

Submits a runnable task and returns a tracked handle.

Parameters

• task - A fallible background action with no business return value.

Returns

Ok(handle) if the service accepts the task. The handle exposes status, pre-start cancellation, and final unit result retrieval.

Errors

Returns SubmissionError when the service refuses the task before accepting it.

fn is_running(&self) -> bool

Returns whether the service accepts new tasks.

Returns

true only while the lifecycle is ExecutorServiceLifecycle::Running.

fn is_shutting_down(&self) -> bool

Returns whether graceful shutdown is in progress.

Returns

true only while the lifecycle is ExecutorServiceLifecycle::ShuttingDown.

fn is_stopping(&self) -> bool

Returns whether abrupt stop is in progress.

Returns

true only while the lifecycle is ExecutorServiceLifecycle::Stopping.

fn is_not_running(&self) -> bool

Returns whether this service is not running.

Returns

true once the service has started graceful shutdown, abrupt stop, or has already terminated.

fn is_terminated(&self) -> bool

Returns whether the service has terminated.

Returns

true only after shutdown or stop has been requested and all accepted tasks have completed or been cancelled.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl ExecutorService for ThreadPerTaskExecutorService

type ResultHandle<R, E> = TaskHandle<R, E> where R: Send + 'static, E: Send + 'static

type TrackedHandle<R, E> = TrackedTask<R, E> where R: Send + 'static, E: Send + 'static