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.

Show on GitHub

  • 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 }
    Show on GitHub

  • Submit a given task to be executed by the EventLoop

    Declaration

    Swift

    func execute(_ task: @escaping () -> Void)
    Show on GitHub
  • 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.

    Show on GitHub

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

    Note

    You can only cancel a task before it has started executing.

    Declaration

    Swift

    @discardableResult
func scheduleTask<T>(deadline: NIODeadline, _ task: @escaping () throws -> T) -> Scheduled<T>

    Parameters

    task

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

    Return Value

    A Scheduled object which may be used to cancel the task if it has not yet run, or to wait on the completion of the task.

    Show on GitHub

  • Schedule a task that is executed by this EventLoop after the given amount of time.

    Note

    You can only cancel a task before it has started executing.

    Note

    The in value is clamped to a maximum when running on a Darwin-kernel.

    Declaration

    Swift

    @discardableResult
func scheduleTask<T>(in: TimeAmount, _ task: @escaping () throws -> T) -> Scheduled<T>

    Parameters

    task

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

    Return Value

    A Scheduled object which may be used to cancel the task if it has not yet run, or to wait on the completion of the task.

    Show on GitHub
  • preconditionInEventLoop(file:line:) Default implementation

    Asserts that the current thread is the one tied to this EventLoop. Otherwise, the process will be abnormally terminated as per the semantics of preconditionFailure(_:file:line:).

    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)
    Show on GitHub

  • Asserts that the current thread is not the one tied to this EventLoop. Otherwise, the process will be abnormally terminated as per the semantics of preconditionFailure(_:file:line:).

    Default Implementation

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

    Declaration

    Swift

    func preconditionNotInEventLoop(file: StaticString, line: UInt)
    Show on GitHub
  • makeSucceededVoidFuture() Default implementation

    Return a succeeded Void future.

    Semantically, this function is equivalent to calling makeSucceededFuture(()). Contrary to makeSucceededFuture, makeSucceededVoidFuture is a customization point for EventLoops which allows EventLoops to cache a pre-succeded Void future to prevent superfluous allocations.

    Default Implementation

    Default implementation of makeSucceededVoidFuture: Return a fresh future (which will allocate).

    Declaration

    Swift

    func makeSucceededVoidFuture() -> EventLoopFuture<Void>
    Show on GitHub
  • 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 asynchronous task to run. As with everything that runs on the EventLoop, it must not block.

    Return Value

    An EventLoopFuture identical to the EventLoopFuture returned from task.

    Show on GitHub

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

    Note

    You can only cancel a task before it has started executing.

    Declaration

    Swift

    @discardableResult
@inlinable
public func flatScheduleTask<T>(deadline: NIODeadline,
                                file: StaticString = #file,
                                line: UInt = #line,
                                _ task: @escaping () throws -> EventLoopFuture<T>) -> Scheduled<T>

    Parameters

    task

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

    Return Value

    A Scheduled object which may be used to cancel the task if it has not yet run, or to wait on the full execution of the task, including its returned EventLoopFuture.

    Show on GitHub

  • Schedule a task that is executed by this EventLoop after the given amount of time.

    Note

    You can only cancel a task before it has started executing.

    Declaration

    Swift

    @discardableResult
@inlinable
public func flatScheduleTask<T>(in delay: TimeAmount,
                                file: StaticString = #file,
                                line: UInt = #line,
                                _ task: @escaping () throws -> EventLoopFuture<T>) -> Scheduled<T>

    Parameters

    task

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

    Return Value

    A Scheduled object which may be used to cancel the task if it has not yet run, or to wait on the full execution of the task, including its returned EventLoopFuture.

    Show on GitHub
  • 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>
    Show on GitHub

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

    Show on GitHub

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

    Show on GitHub
  • 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.

    Show on GitHub
  • close() Extension method

    Close this EventLoop.

    Declaration

    Swift

    public func close() throws
    Show on GitHub

  • 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.
    Show on GitHub

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

    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. Task will keep repeating regardless of whether the future gets fulfilled with success or error.
    Show on GitHub
  • makeIterator() Extension method

    Returns an EventLoopIterator over this EventLoop.

    Declaration

    Swift

    public func makeIterator() -> EventLoopIterator

    Return Value

    EventLoopIterator

    Show on GitHub

  • Asserts that the current thread is the one tied to this EventLoop. Otherwise, if running in debug mode, the process will be abnormally terminated as per the semantics of preconditionFailure(_:file:line:). Never has any effect in release mode.

    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)
    Show on GitHub

  • Asserts that the current thread is not the one tied to this EventLoop. Otherwise, if running in debug mode, the process will be abnormally terminated as per the semantics of preconditionFailure(_:file:line:). Never has any effect in release mode.

    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 assertNotInEventLoop(file: StaticString = #file, line: UInt = #line)
    Show on GitHub