Class ConfiguredExecutorProvider
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final recordThe sizes of a pool: the number of threads it keeps even when they are idle and the maximum number of its threads. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe configuration key for the number of threads a pool keeps even when they are idle.static final StringThe configuration key for whether the threads of a pool are daemon threads.static final StringThe 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.static final StringThe configuration key for the witness of the key domain of an object-specific pool.static final StringThe configuration key for the maximum number of threads of a pool.static final StringThe configuration key for the log level the pool statistics of a pool need to reach.static final StringThe prefix of the configuration of the pools, below which the name of a pool follows.static final StringThe configuration key for the priority of the threads of a pool.static final StringThe configuration key for the amount of queued tasks before warnings are logged.static final StringThe configuration key for the stack size of the threads of a pool, in KiB.static final StringThe configuration key for the name prefix of the threads of a pool.static final intThe number of threads a plain or object-specific pool keeps when neither its configuration nor its providing service states one.static final intThe maximum number of threads of a pool when neither its configuration nor its providing service states one.static final intThe number of threads of a scheduled pool when neither its configuration nor its providing service states one.static final longThe stack size of the threads of a pool that does not configure one, in KiB. -
Constructor Summary
ConstructorsConstructorDescriptionConfiguredExecutorProvider(Configuration configuration, Logger logger) Creates a pool management for the service having the designated configuration, with the generic defaults for every pool.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.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. -
Method Summary
Modifier and TypeMethodDescriptionvoidawaitTermination(boolean emergency) Awaits the termination of every pool this provider created, aftershutdown(boolean)has shut them down.<T extends Executor>
TgetExecutor(String name, Class<T> cls, Class<?>... typeArgs) Gets the pool of the designated name, creating it on the first request.voidshutdown(boolean emergency) Shuts down every pool this provider created, as part of shutting the providing service down.
-
Field Details
-
CONF_PREFIX
The prefix of the configuration of the pools, below which the name of a pool follows.- See Also:
-
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
The configuration key for the number of threads a pool keeps even when they are idle.- See Also:
-
CONF_MAX_POOL_SIZE
The configuration key for the maximum number of threads of a pool.- See Also:
-
CONF_STACK_SIZE
The configuration key for the stack size of the threads of a pool, in KiB.- See Also:
-
CONF_PRIORITY
The configuration key for the priority of the threads of a pool.- See Also:
-
CONF_DAEMON
The configuration key for whether the threads of a pool are daemon threads.- See Also:
-
CONF_THREAD_NAME
The configuration key for the name prefix of the threads of a pool.- See Also:
-
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
The configuration key for the log level the pool statistics of a pool need to reach.- See Also:
-
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_SIZEThe 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_SIZEThe 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_SIZEThe 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_SIZEThe 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
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 benull.logger- The logger of the providing service. This must not benull.
-
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 benull.logger- The logger of the providing service. This must not benull.defaultSizes- The sizes of pools by their name, applying where the configuration of such a pool states no size. This must not benull.
-
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 acancel(true)as acancel(false).- Parameters:
configuration- The configuration of the providing service, below which the pools are configured. This must not benull.logger- The logger of the providing service. This must not benull.defaultSizes- The sizes of pools by their name, applying where the configuration of such a pool states no size. This must not benull.plainFuturePools- The names of the pools handing out plain futures, which carry interruption from a consumer into the pool. This must not benull.
-
-
Method Details
-
getExecutor
Gets the pool of the designated name, creating it on the first request. This servesExecutorProviderService.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 benull.cls- The type of the requested executor. This must not benull.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, anIllegalArgumentExceptionwill be thrown.RejectedExecutionException- If this provider has been shut down, aRejectedExecutionExceptionwill 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, aftershutdown(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, seeExecutorTools.awaitTermination(ExecutorService, boolean, Logger).- Parameters:
emergency- Whether the providing service is shut down due to an emergency, which waits briefly only.
-