EventLoop

public protocol EventLoop : EventLoopGroup

An EventLoop processes IO / tasks in an endless loop for Channels until it’s closed.

Usually multiple Channels share the same EventLoop for processing IO / tasks and so share the same processing NIOThread. For a better understanding of how such an EventLoop works internally the following pseudo code may be helpful:

while eventLoop.isOpen {
    /// Block until there is something to process for 1...n Channels
    let readyChannels = blockUntilIoOrTasksAreReady()
    /// Loop through all the Channels
    for channel in readyChannels {
        /// Process IO and / or tasks for the Channel.
        /// This may include things like:
        ///    - accept new connection
        ///    - connect to a remote host
        ///    - read from socket
        ///    - write to socket
        ///    - tasks that were submitted via EventLoop methods
        /// and others.
        processIoAndTasks(channel)
    }
}

Because an EventLoop may be shared between multiple Channels it’s important to NOT block while processing IO / tasks. This also includes long running computations which will have the same effect as blocking in this case.

  • Returns true if the current NIOThread is the same as the NIOThread that is tied to this EventLoop. false otherwise.

    Declaration

    Swift

    var inEventLoop: Bool { get }
  • Submit a given task to be executed by the EventLoop

    Declaration

    Swift

    func execute(_ task: @escaping () -> Void)
  • submit(_:) Default implementation

    Submit a given task to be executed by the EventLoop. Once the execution is complete the returned EventLoopFuture is notified.

    Default Implementation

    Submit task to be run on this EventLoop.

    The returned EventLoopFuture will be completed when task has finished running. It will be succeeded with task‘s return value or failed if the execution of task threw an error.

    Declaration

    Swift

    func submit<T>(_ task: @escaping () throws -> T) -> EventLoopFuture<T>

    Parameters

    task

    The closure that will be submitted to the EventLoop for execution.

    Return Value

    EventLoopFuture that is notified once the task was executed.

  • Schedule a task that is executed by this SelectableEventLoop at the given time.

    Declaration

    Swift

    @discardableResult
    func scheduleTask<T>(deadline: NIODeadline, _ task: @escaping () throws -> T) -> Scheduled<T>
  • Schedule a task that is executed by this SelectableEventLoop after the given amount of time.

    Declaration

    Swift

    @discardableResult
    func scheduleTask<T>(in: TimeAmount, _ task: @escaping () throws -> T) -> Scheduled<T>
  • preconditionInEventLoop(file:line:) Default implementation

    Checks that this call is run from the EventLoop. If this is called from within the EventLoop this function will have no effect, if called from outside the EventLoop it will crash the process with a trap.

    Default Implementation

    Checks the necessary condition of currently running on the called EventLoop for making forward progress.

    Declaration

    Swift

    func preconditionInEventLoop(file: StaticString, line: UInt)
  • flatSubmit(_:) Extension method

    Submit task to be run on this EventLoop.

    The returned EventLoopFuture will be completed when task has finished running. It will be identical to the EventLoopFuture returned by task.

    Declaration

    Swift

    @inlinable
    public func flatSubmit<T>(_ task: @escaping () -> EventLoopFuture<T>) -> EventLoopFuture<T>

    Parameters

    task

    The synchronous task to run. As everything that runs on the EventLoop, it must not block.

    Return Value

    An EventLoopFuture identical to the EventLooopFuture returned from task.

  • makePromise(of:file:line:) Extension method

    Creates and returns a new EventLoopPromise that will be notified using this EventLoop as execution NIOThread.

    Declaration

    Swift

    @inlinable
    public func makePromise<T>(of type: T.Type = T.self, file: StaticString = #file, line: UInt = #line) -> EventLoopPromise<T>
  • Creates and returns a new EventLoopFuture that is already marked as failed. Notifications will be done using this EventLoop as execution NIOThread.

    Declaration

    Swift

    @inlinable
    public func makeFailedFuture<T>(_ error: Error, file: StaticString = #file, line: UInt = #line) -> EventLoopFuture<T>

    Parameters

    error

    the Error that is used by the EventLoopFuture.

    Return Value

    a failed EventLoopFuture.

  • Creates and returns a new EventLoopFuture that is already marked as success. Notifications will be done using this EventLoop as execution NIOThread.

    Declaration

    Swift

    @inlinable
    public func makeSucceededFuture<Success>(_ value: Success, file: StaticString = #file, line: UInt = #line) -> EventLoopFuture<Success>

    Parameters

    result

    the value that is used by the EventLoopFuture.

    Return Value

    a succeeded EventLoopFuture.

  • next() Extension method

    An EventLoop forms a singular EventLoopGroup, returning itself as the ‘next’ EventLoop.

    Declaration

    Swift

    public func next() -> EventLoop

    Return Value

    Itself, because an EventLoop forms a singular EventLoopGroup.

  • close() Extension method

    Close this EventLoop.

    Declaration

    Swift

    public func close() throws
  • Schedule a repeated task to be executed by the EventLoop with a fixed delay between the end and start of each task.

    Declaration

    Swift

    @discardableResult
    public func scheduleRepeatedTask(initialDelay: TimeAmount, delay: TimeAmount, notifying promise: EventLoopPromise<Void>? = nil, _ task: @escaping (RepeatedTask) throws -> Void) -> RepeatedTask

    Parameters

    initialDelay

    The delay after which the first task is executed.

    delay

    The delay between the end of one task and the start of the next.

    promise

    If non-nil, a promise to fulfill when the task is cancelled and all execution is complete.

    task

    The closure that will be executed.

  • Schedule a repeated asynchronous task to be executed by the EventLoop with a fixed delay between the end and start of each task.

    Note

    The delay is measured from the completion of one run’s returned future to the start of the execution of the next run. For example: If you schedule a task once per second but your task takes two seconds to complete, the time interval between two subsequent runs will actually be three seconds (2s run time plus the 1s delay.)

  • return: RepeatedTask

  • Declaration

    Swift

    @discardableResult
    public func scheduleRepeatedAsyncTask(initialDelay: TimeAmount,
                                          delay: TimeAmount,
                                          notifying promise: EventLoopPromise<Void>? = nil,
                                          _ task: @escaping (RepeatedTask) -> EventLoopFuture<Void>) -> RepeatedTask

    Parameters

    initialDelay

    The delay after which the first task is executed.

    delay

    The delay between the end of one task and the start of the next.

    promise

    If non-nil, a promise to fulfill when the task is cancelled and all execution is complete.

    task

    The closure that will be executed.

  • makeIterator() Extension method

    Returns an EventLoopIterator over this EventLoop.

    Declaration

    Swift

    public func makeIterator() -> EventLoopIterator

    Return Value

    EventLoopIterator

  • Checks that this call is run from the EventLoop. If this is called from within the EventLoop this function will have no effect, if called from outside the EventLoop it will crash the process with a trap if run in debug mode. In release mode this function never has any effect.

    Note

    This is not a customization point so calls to this function can be fully optimized out in release mode.

    Declaration

    Swift

    @inlinable
    public func assertInEventLoop(file: StaticString = #file, line: UInt = #line)