folly::MuxIOThreadPoolExecutor

Synopsis

Declared in <folly/io/async/MuxIOThreadPoolExecutor.h>

class MuxIOThreadPoolExecutor
    : public IOThreadPoolExecutorBase

Description

A pool of EventBases scheduled over a pool of threads.

Intended as a drop-in replacement for folly::IOThreadPoolExecutor, but with a substantially different design: EventBases are not pinned to threads, so it is possible to have more EventBases than threads. EventBases that have ready events can be scheduled on any of the threads in the pool, with the scheduling governed by ThrottledLifoSem.

This allows to batch the loops of multiple EventBases on a single thread as long as each runs for a short enough time, reducing the number of wake-ups and allowing for better load balancing across handlers. For example, we can create a large number of EventBases processed by a smaller number of threads and distribute the handlers.

The number of EventBases is set at construction time and cannot be changed later. The number of threads can be changed dynamically, but setting it to 0 is not supported (otherwise no thread would be left to drive the EventBases) and it is not useful to run more threads than EventBases, so that is not supported either: attempting to set the number of threads to 0 or to a value greater than numEventBases() (either in construction or using setNumThreads()) will throw std::invalid_argument).

Base Classes

Name	Description
`IOThreadPoolExecutorBase`	Base interface for executors that run tasks on IO threads with EventBases.

Types

Name	Description
`DequeuedTaskInfo`	Task metadata recorded when a task is dequeued.
`IOObserver`	Observer that is notified when EventBases are registered.
`Observer`	Observer interface for thread start/stop. Provides hooks so actions can be taken when threads are created
`Options`	Configuration options for the executor.
`PoolStats`	Snapshot of thread pool statistics.
`ProcessedTaskInfo`	Task metadata recorded after a task finishes processing.
`TaskInfo`	Task metadata recorded when a task is enqueued.
`TaskObserver`	Interface for observing task lifecycle events.
`ThreadHandle`	Base class for threads created with ThreadPoolExecutor. Some subclasses have methods that operate on these handles.
`WeakRefExecutor`	Marker base for the weak-reference executor wrappers.

Type Aliases

Name	Description
`KeepAlive`	Alias for ExecutorKeepAlive, a safe pointer to an Executor.
`TaskStats`	Alias for ProcessedTaskInfo used by the legacy stats callback.
`TaskStatsCallback`	Callback invoked with per-task stats.

Member Functions

Name	Description
`MuxIOThreadPoolExecutor` [constructor]	Constructs the executor.
`~MuxIOThreadPoolExecutor` [destructor] [virtual]	Destroys the executor, stopping and joining its threads.
`add`	`add` overloads
`addObserver`	`addObserver` overloads
`addTaskObserver`	Adds a task observer.
`addWithPriority` [virtual]	Enqueue a function with a given priority, where 0 is the medium priority This is up to the implementation to enforce
`getAllEventBases` [virtual]	Returns all the EventBase instances.
`getEventBase` [virtual]	Returns one of the EventBases in the pool.
`getEventBaseManager` [virtual]	Returns the EventBaseManager used by the executor.
`getName`	Returns the name of the thread pool.
`getNumPriorities` [virtual]	Returns the number of priority levels this executor supports.
`getPendingTaskCount`	Returns the number of tasks waiting to be executed.
`getPoolStats`	Returns a snapshot of the pool's statistics.
`getThreadFactory`	Returns the factory used to create pool threads.
`getThreadIdCollector` [virtual]	Returns the worker id collector.
`getUsedCpuTime`	Return the cumulative CPU time used by all threads in the pool, including those that are no longer alive. Requires system support for per-thread CPU clocks. If not available, the function returns 0. This operation can be expensive.
`join` [virtual]	Stops the executor and waits for its threads to finish.
`numActiveThreads`	Returns the actual number of active threads, which can differ from numThreads() due to ThreadPoolExecutor's dynamic behavior.
`numEventBases`	Returns the number of EventBases in the pool.
`numThreads`	Returns the configured number of threads in the pool.
`removeObserver`	`removeObserver` overloads
`setNumThreads`	Sets the configured number of threads in the pool.
`setThreadDeathTimeout`	Sets the idle timeout after which a dynamic thread may be reaped.
`setThreadFactory`	Sets the factory used to create pool threads.
`stop` [virtual]	Stops the executor without waiting for its threads to finish.
`subscribeToTaskStats` [deprecated]	Subscribes a callback to receive per-task stats.
`weakRef`	Returns a weak keep-alive to this executor.

Static Member Functions

Name	Description
`getKeepAliveToken`	`getKeepAliveToken` overloads
`getWeakRef`	Returns a weak keep-alive to `executor` that does not extend its lifetime.
`invokeCatchingExns`	Invokes `f`, logging and swallowing any exception it throws.
`withAll`	Execute f against all ThreadPoolExecutors, primarily for retrieving and exporting stats.

Static Data Members

Name	Description
`HI_PRI`	Highest schedulable priority.
`LO_PRI`	Lowest schedulable priority.
`MID_PRI`	Medium (default) schedulable priority.

Using Declarations

Name	Description
`IOThreadPoolExecutorBase`	Inherits the ThreadPoolExecutor constructors.

Protected Types

Name	Description
`StoppedThreadQueue`	Blocking queue holding threads that have stopped and await joining.
`Task`	A unit of work enqueued in the executor along with its metadata.
`Thread`	Handle and bookkeeping for a single pool worker thread.
`ThreadList`	Ordered container of pool threads keyed by thread id.

Protected Type Aliases

Name	Description
`ThreadPtr`	Shared pointer to a pool Thread.

Protected Member Functions

Name	Description
`addThreads`	Starts n new threads.
`afterConstructThreads`	Performs post-construction setup for newly created threads.
`destroyTaskObservers`	Destroys all task observers.
`ensureActiveThreads`	Starts additional pool threads if needed to handle pending work.
`ensureJoined`	Joins idle threads that were destroyed and still need joining.
`ensureMaxActiveThreads`	Ensures the number of active threads is raised toward the maximum.
`forEachTaskObserver`	Invokes a function for each registered task observer.
`getPendingTaskCountImpl` [virtual]	Returns the number of pending tasks.
`handleObserverRegisterThread` [virtual]	Handles registration of a thread with an observer.
`handleObserverUnregisterThread` [virtual]	Handles unregistration of a thread with an observer.
`joinAndResetKeepAlive`	Joins the keep-alive, then reinstates a fresh one so the executor is reusable.
`joinKeepAlive`	Releases this executor's own keep-alive and waits for all others to drain.
`joinKeepAliveOnce`	Joins the keep-alive token the first time it is called.
`joinStoppedThreads`	Joins n stopped threads and removes them from the waiting queue.
`keepAliveAcquire` [virtual]	Acquire a keep alive token. Should return false if keep-alive mechanism is not supported.
`keepAliveRelease` [virtual]	Release a keep alive token previously acquired by keepAliveAcquire(). Will never be called if keepAliveAcquire() returns false.
`makeThread` [virtual]	Creates a suitable Thread struct.
`minActive`	Returns whether the pool is at its minimum active thread count.
`registerTaskEnqueue`	Notifies observers that a task has been enqueued.
`removeThreads`	Removes n threads from the pool.
`runTask`	Runs a task on the given thread.
`stopAndJoinAllThreads`	Stops and joins all threads to implement shutdown.
`stopThreads` [virtual]	Stops n threads, moving their ThreadPtrs to the stoppedThreads_ queue and removing them from threadList_, either synchronously or asynchronously.
`threadRun` [virtual]	The function bound to pool threads.
`tryAddOneThread`	Tries to start one new thread.
`tryTimeoutThread`	Tries to time out and stop one idle thread.
`validateNumThreads` [virtual]	Validates a requested thread count, throwing on invalid values.

Protected Static Member Functions

Name	Description
`deregisterThreadPoolExecutor`	Deregisters a thread pool executor from the global list.
`fillTaskInfo`	Fills task info metadata from a task.
`isKeepAliveDummy`	Returns true if the KeepAlive is constructed from an executor that does not support the keep alive ref-counting functionality
`keepAliveAcquire`	Acquires a keep-alive reference on `executor`.
`keepAliveRelease`	Releases a keep-alive reference on `executor`.
`makeKeepAlive`	Makes a counted (non-dummy, non-alias) keep-alive referring to `executor`.
`registerThreadPoolExecutor`	Registers a thread pool executor with the global list.

Protected Data Members

Name	Description
`activeThreads_`	Current number of active threads.
`isJoin_`	Whether the current downsizing is a join.
`keepAliveJoined_`	Whether the keep-alive token has already been joined.
`maxThreads_`	Maximum number of threads in the pool.
`minThreads_`	Minimum number of threads in the pool.
`observers_`	Registered thread start/stop observers.
`stoppedThreadProcessedTasks_`	Number of tasks processed by stopped or joined threads. Updated when a thread stops, which preceeds joining. Requires holding the threadListLock_.
`stoppedThreads_`	Queue of stopped threads awaiting join.
`threadFactory_`	Factory used to create pool threads.
`threadListLock_`	Guards access to threadList_.
`threadList_`	List of live pool threads.
`threadPoolHook_`	Hook registering this executor with the global thread pool list.
`threadTimeout_`	Idle timeout after which a dynamic thread may be reaped.
`threadsCanTimeout_`	Whether idle threads are allowed to time out and stop.
`threadsToJoin_`	Number of idle threads pending join.

Non-Member Functions

Name	Description
`async_tracing::logFutureVia`	Trace hook invoked when a Future is rescheduled onto an executor.
`async_tracing::logGetGlobalCPUExecutor`	Trace hook invoked when the global CPU executor is retrieved.
`async_tracing::logGetGlobalIOExecutor`	Trace hook invoked when the global IO executor is retrieved.
`async_tracing::logGetImmutableCPUExecutor`	Trace hook invoked when the immutable CPU executor is retrieved.
`async_tracing::logGetImmutableIOExecutor`	Trace hook invoked when the immutable IO executor is retrieved.
`async_tracing::logSemiFutureVia`	Trace hook invoked when a SemiFuture is rescheduled onto an executor.
`async_tracing::logSetGlobalCPUExecutor`	Trace hook invoked when the global CPU executor is set.
`async_tracing::logSetGlobalIOExecutor`	Trace hook invoked when the global IO executor is set.