Class ConfiguredExecutorProvider

java.lang.Object
de.aristaflow.adept2.base.service.ConfiguredExecutorProvider

public class ConfiguredExecutorProvider extends Object
The pool management of a service that provides thread pools, that is of an ExecutorProviderService. It is deliberately no base class: a marker on a base that services are built on would make every one of them a provider, so a service opts in by declaring the contract and delegates to an instance of this class.

A pool is created on the first request for its name and lives until this provider shuts down. Its configuration is tuning and never a precondition: an unconfigured name is served with the defaults the providing service states for it or the generic ones, both documented, and one log line, since the set of requestable names is static in the installed code rather than in the configuration. The keys below a name are "CorePoolSize", "MaxPoolSize", "StackSize", "Priority", "Daemon", "ThreadName", "QueueLimitPoolStatistics", "MinLogLevelPoolStatistics" and, for an object-specific pool, "IndexType".

The type a name is first requested as decides the kind of its pool: an object-specific pool for an UnlimitedPipelineExecutor, a plain pool growing from its core to its maximum size while work is pending for an ExecutorService and every other type such a pool has, and a scheduled pool for a ScheduledExecutorService. A scheduled pool runs delayed and periodic work on a fixed number of threads, its core pool size, which is at least one; the maximum pool size and the pool statistics do not apply to it, and a configured one is ignored with a warning.

"IndexType" is the witness of the key domain, written as the type arguments of a request are: each class followed by the arguments of its own type parameters. It confirms the domain a consumer states and never overrides it, the declaration being the source that always exists while the configuration is what an operator can read. Where a name is served without a configured witness, the arguments of the first request become the witness of the pool, and a later request disagreeing with it is refused: a pool is one ordering domain, so two consumers keying it differently would share pipelines without either of them being able to notice.

The futures the pools hand out are interrupt-shielded: a cancel(true) is served as a cancel(false), so the rule that a consumer never interrupts a thread of the provider holds by construction rather than by discipline. The providing service declares a pool to hand out plain futures instead where it also hands that pool out through an accessor of its own, whose callers may rely on interrupting the work they cancel; a consumer of such a pool keeps the rule by discipline.

  • Field Details

    • CONF_PREFIX

      public static final String CONF_PREFIX
      The prefix of the configuration of the pools, below which the name of a pool follows.
      See Also:
    • CONF_DOCUMENTED_PREFIX

      public static final String CONF_DOCUMENTED_PREFIX
      The prefix of the keys of one pool for documenting them, the name of the pool being a placeholder: the set of names is static in the installed code, so the keys of a pool cannot be declared with a fixed name and are documented as a pattern instead.
      See Also:
    • CONF_CORE_POOL_SIZE

      public static final String CONF_CORE_POOL_SIZE
      The configuration key for the number of threads a pool keeps even when they are idle.
      See Also:
    • CONF_MAX_POOL_SIZE

      public static final String CONF_MAX_POOL_SIZE
      The configuration key for the maximum number of threads of a pool.
      See Also:
    • CONF_STACK_SIZE

      public static final String CONF_STACK_SIZE
      The configuration key for the stack size of the threads of a pool, in KiB.
      See Also:
    • CONF_PRIORITY

      public static final String CONF_PRIORITY
      The configuration key for the priority of the threads of a pool.
      See Also:
    • CONF_DAEMON

      public static final String CONF_DAEMON
      The configuration key for whether the threads of a pool are daemon threads.
      See Also:
    • CONF_THREAD_NAME

      public static final String CONF_THREAD_NAME
      The configuration key for the name prefix of the threads of a pool.
      See Also:
    • CONF_QUEUE_LIMIT_POOL_STATISTICS

      public static final String CONF_QUEUE_LIMIT_POOL_STATISTICS
      The configuration key for the amount of queued tasks before warnings are logged.
      See Also:
    • CONF_MIN_LOG_LEVEL_POOL_STATISTICS

      public static final String CONF_MIN_LOG_LEVEL_POOL_STATISTICS
      The configuration key for the log level the pool statistics of a pool need to reach.
      See Also:
    • CONF_INDEX_TYPE

      public static final String CONF_INDEX_TYPE
      The configuration key for the witness of the key domain of an object-specific pool.
      See Also:
    • DEFAULT_CORE_POOL_SIZE

      public static final int DEFAULT_CORE_POOL_SIZE
      The number of threads a plain or object-specific pool keeps when neither its configuration nor its providing service states one. Keeping none is not a pool without threads: the core grows to the maximum as soon as more work than the core size is pending and shrinks again when the queue drains.
      See Also:
    • DEFAULT_SCHEDULED_CORE_POOL_SIZE

      public static final int DEFAULT_SCHEDULED_CORE_POOL_SIZE
      The number of threads of a scheduled pool when neither its configuration nor its providing service states one. A scheduled pool keeps a fixed number of threads and needs at least one: without a core thread, its one thread polls for the waiting work every ten milliseconds instead of awaiting it.
      See Also:
    • DEFAULT_MAX_POOL_SIZE

      public static final int DEFAULT_MAX_POOL_SIZE
      The maximum number of threads of a pool when neither its configuration nor its providing service states one. One blocked consumer occupies at most one pipeline and therefore at most one thread, so this states how much misbehaviour a pool absorbs.
      See Also:
    • DEFAULT_STACK_SIZE

      public static final long DEFAULT_STACK_SIZE
      The stack size of the threads of a pool that does not configure one, in KiB. Zero leaves the size to the platform, which is what a pool wants: a small stack limits the damage of an uncontrolled number of threads, and the number of threads of a pool is controlled.
      See Also:
  • Constructor Details

    • ConfiguredExecutorProvider

      public ConfiguredExecutorProvider(Configuration configuration, Logger logger)
      Creates a pool management for the service having the designated configuration, with the generic defaults for every pool.
      Parameters:
      configuration - The configuration of the providing service, below which the pools are configured. This must not be null.
      logger - The logger of the providing service. This must not be null.
    • ConfiguredExecutorProvider

      public ConfiguredExecutorProvider(Configuration configuration, Logger logger, Map<String,ConfiguredExecutorProvider.PoolSizes> defaultSizes)
      Creates a pool management for the service having the designated configuration, with the designated sizes as the defaults of the pools they name. A providing service states them for the pools whose consumers it knows, where the generic defaults do not fit; the configuration of a pool overrides them as it overrides the generic ones.
      Parameters:
      configuration - The configuration of the providing service, below which the pools are configured. This must not be null.
      logger - The logger of the providing service. This must not be null.
      defaultSizes - The sizes of pools by their name, applying where the configuration of such a pool states no size. This must not be null.
    • ConfiguredExecutorProvider

      public ConfiguredExecutorProvider(Configuration configuration, Logger logger, Map<String,ConfiguredExecutorProvider.PoolSizes> defaultSizes, Collection<String> plainFuturePools)
      Creates a pool management for the service having the designated configuration, with the designated sizes as the defaults of the pools they name and plain futures for the designated pools. A providing service declares plain futures for a pool it also hands out through an accessor of its own, whose callers may rely on interrupting the work they cancel; every other pool serves a cancel(true) as a cancel(false).
      Parameters:
      configuration - The configuration of the providing service, below which the pools are configured. This must not be null.
      logger - The logger of the providing service. This must not be null.
      defaultSizes - The sizes of pools by their name, applying where the configuration of such a pool states no size. This must not be null.
      plainFuturePools - The names of the pools handing out plain futures, which carry interruption from a consumer into the pool. This must not be null.
  • Method Details

    • getExecutor

      public <T extends Executor> T getExecutor(String name, Class<T> cls, Class<?>... typeArgs)
      Gets the pool of the designated name, creating it on the first request. This serves ExecutorProviderService.getExecutor(String, Class, Class...) of the providing service.
      Type Parameters:
      T - The type of the requested executor.
      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, stating the key domain of an object-specific pool.
      Returns:
      The pool of the designated name. This will never be null.
      Throws:
      IllegalArgumentException - If the designated type has type parameters but no arguments are stated, if the arguments disagree with the domain the name already serves or with a configured witness, if a pool created for this request configures a priority outside the range of thread priorities, if it is a scheduled pool without a core thread or another pool with a maximum pool size below 1 or a core pool size outside the range from 0 to that maximum, or if the designated type is none this provider creates, an IllegalArgumentException will be thrown.
      RejectedExecutionException - If this provider has been shut down, a RejectedExecutionException will be thrown.
    • shutdown

      public void shutdown(boolean emergency)
      Shuts down every pool this provider created, as part of shutting the providing service down. A normal shutdown lets the pools complete their queued work, a scheduled pool its due work only, dropping the delayed and periodic work still waiting; an emergency shutdown interrupts the running work and drops the queued work. A pool is refused from then on. This tolerates a shutdown before any pool was requested, which has nothing to shut down, as well as a repeated one.

      The termination is awaited separately by awaitTermination(boolean), so that the providing service can shut its other executors down in between and their terminations overlap.

      Parameters:
      emergency - Whether the providing service is shut down due to an emergency.
    • awaitTermination

      public void awaitTermination(boolean emergency)
      Awaits the termination of every pool this provider created, after shutdown(boolean) has shut them down. The wait is bounded as for shutting a service down: a pool which has not terminated in time is shut down immediately and eventually given up with a warning naming it, see ExecutorTools.awaitTermination(ExecutorService, boolean, Logger).
      Parameters:
      emergency - Whether the providing service is shut down due to an emergency, which waits briefly only.