Interface ExecutorProviderService

All Known Implementing Classes:
MultiplexingClientService

public interface ExecutorProviderService
An ExecutorProviderService provides the named, individually configured thread pools on which objects completed by an injection driver do their work. A pool is shared by every consumer requesting its name, which is what allows an object that would otherwise run a thread of its own to give that thread up.

The name carries the contract: it denotes one pool and, for an object-specific executor, one key domain. A second consumer requests an existing name only where sharing that domain is the deliberate point – a name may say so, as a name for plain unspecific work does, but the platform does not police key spaces. Sizes, queue, priority, daemon and thread naming are tuning of the provider configuration; a name that is not configured is served with documented defaults, so configuration is never a precondition for running.

Implementing this interface is the opt-in of a service to provide, and it is declared by implementation classes only, never by a service interface – the proxy layer walks the ancestry of an interface, so a remotable interface extending this one would carry the method into its stubs, where an Executor can neither be serialised nor proxied.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T extends Executor>
    T
    getExecutor(String name, Class<T> cls, Class<?>... typeArgs)
    Gets the executor configured under the designated name having the designated type, e. g.
  • Method Details

    • getExecutor

      <T extends Executor> T getExecutor(String name, Class<T> cls, Class<?>... typeArgs)
      Gets the executor configured under the designated name having the designated type, e. g. an ExecutorService, a ScheduledExecutorService or an UnlimitedPipelineExecutor. The executor is owned by this provider and lives and dies with it, so a caller must never shut it down and never interrupt a thread running its work. A submit arriving after the shutdown of this provider is refused with a RejectedExecutionException, which a caller tolerates the way services tolerate each other during shutdown.

      The futures the returned executor hands out do not carry interruption from a caller into the pool: a cancel(true) is served as a cancel(false), so the rule above holds by construction rather than by discipline. The exception is a pool which this provider also hands out through an accessor of its own, whose callers may rely on interrupting the work they cancel: its futures are plain, and a caller of this method keeps the rule by discipline.

      Type Parameters:
      T - The type of the requested executor, which is the type the first request for the designated name created its pool as, or a supertype hereof.
      Parameters:
      name - The name of the requested pool. This must not be null.
      cls - The type of the requested executor. This must not be null.
      typeArgs - The type arguments of the designated type, in pre-order as the injection annotation encodes them: each class is followed by the arguments of its own type parameters. These are required whenever the designated type has type parameters – for an object-specific executor they state the key domain the caller expects, which this provider matches against the one of the pool. They stay empty for a plain executor.
      Returns:
      The executor configured under the designated name. This will never be null.
      Throws:
      IllegalArgumentException - If the designated type arguments disagree with those the designated name is already serving, or if they are empty although the designated type has type parameters, an IllegalArgumentException will be thrown: such a request either joins a foreign key domain or states no domain at all, and both are undefined rather than merely untuned.