folly::EventBase

Event loop and I/O multiplexer bound to a single thread.

Synopsis

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

class EventBase
    : public TimeoutManager
    , public DrivableExecutor
    , public IOExecutor
    , public SequencedExecutor
    , public ScheduledExecutor
    , public GetThreadIdCollector

Base Classes

NameDescription
TimeoutManagerBase interface to be implemented by all classes expecting to manage timeouts. AsyncTimeout will use implementations of this interface to schedule/cancel timeouts.
DrivableExecutorAn executor that can be driven forward via its drive() method.
IOExecutorAn executor backed by an I/O event loop.
SequencedExecutorAn executor that sequences tasks whose submissions were sequenced.
ScheduledExecutorAn executor that supports timed scheduling. Like RxScheduler.
GetThreadIdCollectorInterface for executors that provide a WorkerProvider to collect thread ids.

Types

NameDescription
FunctionLoopCallback Loop callback that wraps and owns a folly::Function.
FunctionOnDestructionCallback On-destruction callback that wraps and owns a folly::Function.
LoopCallback A callback interface to use with runInLoop()
LoopPollOptions Options controlling a single loopPoll() call.
OnDestructionCallback Base class for user callbacks run during EventBase destruction.
Options Configuration options for constructing an EventBase.
SmoothLoopTime Exponentially-smoothed moving average of loop times.
StackFunctionLoopCallback Loop callback that wraps a function without allocating.

Type Aliases

NameDescription
Duration The duration type used for scheduling.
Func Callable type used for functions scheduled on the EventBase.
KeepAlive Alias for ExecutorKeepAlive, a safe pointer to an Executor.
KeepAliveTraceCallback Trace callback invoked from keepAliveAcquire()/keepAliveRelease().
TimePoint The time point type used for scheduling.
timeout_type Millisecond-resolution timeout duration.
timeout_type_high_res Microsecond-resolution timeout duration.

Enums

NameDescription
InternalEnum Distinguishes internal timeouts from normal ones.
LoopStatus Same semantics as loop(), but, instead of blocking, it returns in a "suspended" state. The caller must continue calling loopWithSuspension() until a non-suspended state is reached.

Member Functions

NameDescription
EventBase [constructor]Constructors
~EventBase [destructor] [virtual]Destroys the EventBase and runs any on-destruction callbacks.
operator= [deleted]Deleted copy assignment.
add add overloads
addExecutionObserver Setup execution observation/instrumentation for every EventHandler executed in this EventBase.
addWithPriority [virtual]Enqueue a function with a given priority, where 0 is the medium priority This is up to the implementation to enforce
attachTimeoutManager [virtual]Attaches a timeout to this EventBase's timeout manager.
bumpHandlingTime [virtual]only EventHandler/AsyncTimeout subclasses and ourselves should ever call this.
cancelTimeout [virtual]Cancels a scheduled timeout on this EventBase.
checkIsInEventBaseThread Equivalent to CHECK(isInEventBaseThread()) (and assert/DCHECK for dcheckIsInEventBaseThread), but it prints more information on failure.
dcheckIsInEventBaseThread Checks in debug builds that the caller is in the EventBase thread.
detachTimeoutManager [virtual]Detaches a timeout from this EventBase's timeout manager.
drive [virtual]Implements the DrivableExecutor interface
getAvgLoopTime Get the average loop time in microseconds (an exponentially-smoothed ave)
getBackend Returns the backend driving the event loop.
getEventBase [virtual]Implements the IOExecutor interface
getExecutionObserverList Gets the execution observer list associated with this EventBase.
getLibeventBase Returns the underlying libevent event_base.
getLibeventMethod Returns the libevent method in use by this EventBase.
getLoopCallbacksStartTime Returns the timepoint at the start of the loop callbacks.
getLoopThreadId Returns the ID of the thread that this event base is running in
getMaxReadAtOnce Returns the maximum number of reads performed per event.
getName Returns the name of the thread that runs this event base.
getNotificationQueueSize Returns the number of pending items in the notification queue.
getNumLoopCallbacks Returns the number of loop callbacks pending execution. If this is non-zero, loopOnce() is guaranteed to run the callbacks without blocking.
getNumPriorities [virtual]Returns the number of priority levels this executor supports.
getObserver Returns the observer attached to this EventBase.
getThreadIdCollector [virtual]Implements the GetThreadIdCollector interface
getVirtualEventBase Returns a VirtualEventBase attached to this EventBase.
inRunningEventBaseThread Returns true if and only if the loop is running in the current thread.
isInEventBaseThread Verify that current thread is the EventBase thread.
isInTimeoutManagerThread [virtual]Returns whether the caller runs in the timeout manager thread.
isRunning Check if the event base loop is running.
loop Runs the event loop.
loopForever Runs the event loop.
loopIgnoreKeepAlive [deprecated]Same as loop(), but doesn't wait for all keep-alive tokens to be released.
loopKeepAliveCount Returns the number of outstanding loop keepalives.
loopOnce Wait for some events to become active, run them, then return.
loopPoll Poll the EventBase for active events, run them, then return. Unlike loopOnce, the expectation is that loopPoll will be called multiple times State is therefore persisted across calls to reflect that there is ongoing polling. Control will be returned to the calling thread between iterations. loopPollSetup and loopPollCleanup manage the maintained state across loopPoll calls.
loopPollCleanup Clears state that was setup for active polling against the EventBase. Call after polling via loopPoolSetup and the subsequent loopPoll calls.
loopPollSetup Sets up state for active polling to be done against the EventBase. Call before polling via subsequent loopPoll calls.
loopWithSuspension Runs the loop, returning in a suspended state instead of blocking.
now [virtual]Get this executor's notion of time. Must be threadsafe.
removeExecutionObserver Removes an execution observer from this EventBase.
resetLoadAvg reset the load average to a desired value
runAfterDelay Runs the given Cob at some time after the specified number of milliseconds. (No guarantees exactly when.)
runAfterLoop Adds a callback that will run immediately after the event loop. This can be used to delay some processing until after all the normal loop callback have been processed for this iteration.
runBeforeLoop Adds a callback that will run immediately before the event loop. This is very similar to runInLoop(), but will not cause the loop to break: For example, this callback could be used to get loop times.
runImmediatelyOrRunInEventBaseThread Like runInEventBaseThread, but runs function immediately instead of at the end of the loop when called from the eventbase thread.
runImmediatelyOrRunInEventBaseThreadAndWait Like runInEventBaseThreadAndWait, except if the caller is already in the event base thread, the functor is simply run inline.
runInEventBaseThread Run the specified function in the EventBase's thread.
runInEventBaseThreadAlwaysEnqueue runInEventBaseThreadAlwaysEnqueue overloads
runInEventBaseThreadAndWait Like runInEventBaseThread, but the caller waits for the callback to be executed.
runInLoop runInLoop overloads
runOnDestruction runOnDestruction overloads
runOnDestructionStart runOnDestructionStart overloads
schedule schedule overloads
scheduleAt scheduleAt overloads
scheduleTimeout [virtual]Schedules a timeout on this EventBase.
scheduleTimeoutHighRes [virtual]Schedules AsyncTimeout to fire after timeout microseconds
setLoadAvgMsec Set smoothing coefficient for loop load average; # of milliseconds for exp(-1) (1/2.71828...) decay.
setMaxLatency Set the maximum desired latency in us and provide a callback which will be called when that latency is exceeded. OBS: This functionality depends on time-measurement.
setMaxReadAtOnce Sets the maximum number of reads performed per event.
setName Set the name of the thread that runs this event base.
setObserver Sets the observer that samples loop activity.
setStrictLoopThread Enable strict loop thread mode. This is intended for executors that take ownership of the EventBase and run it continuously until joined. Once set, it is not possible to unset it.
terminateLoopSoon Causes the event loop to exit soon.
timer Returns the wheel timer, creating it on first use.
tryRunAfterDelay Attempts to run the given Cob after the specified delay.
waitUntilRunning Wait until the event loop starts (after starting the event loop thread).

Static Member Functions

NameDescription
getDefaultBackend Creates the default backend for an EventBase.
getKeepAliveToken getKeepAliveToken overloads
getLibeventVersion Returns the libevent library version string.
getTestBackend Creates a backend suitable for tests.
invokeCatchingExns Invokes f, logging and swallowing any exception it throws.
setKeepAliveAcquireTraceCallback Installs the process-global keep-alive acquire trace callback.
setKeepAliveReleaseTraceCallback Installs the process-global keep-alive release trace callback.

Static Data Members

NameDescription
HI_PRI Highest schedulable priority.
LO_PRI Lowest schedulable priority.
MID_PRI Medium (default) schedulable priority.

Protected Member Functions

NameDescription
clearCobTimeouts Cancels and clears all callback timeouts registered via runAfterDelay.
keepAliveAcquire [virtual]Acquires a keep-alive token on this EventBase.
keepAliveRelease [virtual]Releases a keep-alive token on this EventBase.

Protected Static Member Functions

NameDescription
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.

Friends

NameDescription
folly::EventBaseLocalStorage for data tied to the lifetime of an EventBase.
folly::ScopedEventBaseThreadHelper that runs an EventBase loop on a dedicated std::thread.

Non-Member Functions

NameDescription
getEventBasemethodset Deprecated
getUnsafeMutableGlobalEventBasemethodset Executors
async_tracing::logFutureViaTrace hook invoked when a Future is rescheduled onto an executor.
async_tracing::logGetGlobalCPUExecutorTrace hook invoked when the global CPU executor is retrieved.
async_tracing::logGetGlobalIOExecutorTrace hook invoked when the global IO executor is retrieved.
async_tracing::logGetImmutableCPUExecutorTrace hook invoked when the immutable CPU executor is retrieved.
async_tracing::logGetImmutableIOExecutorTrace hook invoked when the immutable IO executor is retrieved.
async_tracing::logSemiFutureViaTrace hook invoked when a SemiFuture is rescheduled onto an executor.
async_tracing::logSetGlobalCPUExecutorTrace hook invoked when the global CPU executor is set.
async_tracing::logSetGlobalIOExecutorTrace hook invoked when the global IO executor is set.
fibers::getFiberManagerTReturns the fiber manager keyed by the local type Local for evb.