folly::EventBase

An event loop that drives asynchronous I/O and timers.

Synopsis

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

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

Base Classes

Name

Description

TimeoutManager

Base interface to be implemented by all classes expecting to manage timeouts. AsyncTimeout will use implementations of this interface to schedule/cancel timeouts.

DrivableExecutor

An executor that can be driven forward via its drive() method.

IOExecutor

An executor backed by an I/O event loop.

SequencedExecutor

An executor that sequences tasks whose submissions were sequenced.

ScheduledExecutor

An executor that supports timed scheduling. Like RxScheduler.

GetThreadIdCollector

Interface for executors that provide a WorkerProvider to collect thread ids.

Types

Name

Description

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

Name

Description

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

Name

Description

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

Name

Description

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

attachTimeoutManager overloads

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

scheduleTimeout overloads

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