folly::IOThreadPoolExecutor

Synopsis

Declared in <folly/executors/IOThreadPoolExecutor.h>

class IOThreadPoolExecutor
    : public IOThreadPoolExecutorBase

Description

NOTE

Uses event_fd for notification, and waking an epoll loop. There is one queue (NotificationQueue specifically) per thread/epoll. If the thread is already running and not waiting on epoll, we don't make any additional syscalls to wake up the loop, just put the new task in the queue. If any thread has been waiting for more than a few seconds, its stack is madvised away. Currently however tasks are scheduled round robin on the queues, so unless there is no work going on, this isn't very effective. Since there is one queue per thread, there is hardly any contention on the queues - so a simple spinlock around an std::deque is used for the tasks. There is no max queue size. By default, there is one thread per core - it usually doesn't make sense to have more IO threads than this, assuming they don't block.

NOTE

::getEventBase() will return an EventBase you can schedule IO work on directly, chosen round-robin.

NOTE

N.B. For this thread pool, stop() behaves like join() because outstanding tasks belong to the event base and will be executed upon its destruction.

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 an IOThreadPoolExecutor.
`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
`IOThreadPoolExecutor` [constructor]	Constructors
`~IOThreadPoolExecutor` [destructor] [virtual]	Stops the executor and joins all IO threads.
`add`	`add` overloads
`addObserver` [virtual]	Registers an observer for thread start/stop events.
`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]	Ensures that the maximum number of active threads is running and returns the EventBase associated with each thread.
`getEventBase` [virtual]	Returns an EventBase to schedule IO work on, chosen round-robin.
`getEventBaseManager` [virtual]	Returns the EventBaseManager used by this 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 provider used to collect thread ids.
`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 joins all threads, waiting for tasks to finish.
`numActiveThreads`	Returns the actual number of active threads, which can differ from numThreads() due to ThreadPoolExecutor's dynamic behavior.
`numThreads`	Returns the configured number of threads in the pool.
`removeObserver` [virtual]	Removes a previously registered observer.
`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]	stop() is best effort - there is no guarantee that unexecuted tasks won't be executed before it returns. Specifically, IOThreadPoolExecutor's stop() behaves like join().
`subscribeToTaskStats` [deprecated]	Subscribes a callback to receive per-task stats.
`weakRef`	Returns a weak keep-alive to this executor.

Static Member Functions

Name	Description
`getEventBase`	Returns the EventBase associated with a given thread handle.
`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
`IOThread`	A pool thread that owns an EventBase and tracks its pending work.
`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`	`handleObserverRegisterThread` overloads
`handleObserverUnregisterThread`	`handleObserverUnregisterThread` overloads
`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.