Trait ExecutorService 

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

    // 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. Services built with TaskSlot should publish TaskExecutionError::Cancelled for accepted work that is intentionally removed before it starts, typically by calling TaskSlot::cancel_unstarted. 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.

Resource cleanup

Dropping an executor-service handle is not a portable resource-release protocol. Concrete services may request shutdown from Drop, but Drop should not be assumed to block until worker threads, helper threads, runtime tasks, queues, or other service-owned resources have fully exited. Blocking in Drop would make ordinary handle destruction unexpectedly wait for arbitrary user code, blocking calls, or OS-thread tasks that cannot be interrupted.

Code that needs deterministic cleanup must request termination explicitly and then wait for it:

1. Call shutdown to drain accepted work, or stop to request best-effort cancellation or abort of work that has not become non-interruptible.
2. Call wait_termination to block until the service reports that no accepted work remains active.
3. Drop the service handle and any task handles after the wait returns.

If a service owns OS threads or blocking tasks, already-running task bodies can keep external resources such as file descriptors, sockets, locks, or reference-counted objects alive until those task bodies return. Services that need stronger cleanup behavior should expose an explicit close/join API rather than relying on destructor side effects.

Required Associated Types

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

Result handle returned for an accepted callable task.

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

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.

This method is the portable way to wait for service-owned resources to quiesce after an explicit shutdown or stop request. Dropping a service handle is not a substitute for calling this method when deterministic cleanup matters.

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 SingleThreadScheduledExecutorService

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

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

impl ExecutorService for ThreadPerTaskExecutorService

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

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

impl ExecutorService for RayonExecutorService

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

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