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

inEventLoop
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
execute(_:)
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


                    
                    
                    scheduleTask(deadline:_:)

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


                    
                    
                    scheduleTask(in:_:)

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
preconditionNotInEventLoop(file:line:) Default implementation
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


                    
                    
                    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 EventLooopFuture returned from task.

Show on GitHub


                    
                    
                    flatScheduleTask(deadline:file:line:_:)

Extension method

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


                    
                    
                    flatScheduleTask(in:file:line:_:)

Extension method

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


                    
                    
                    makeFailedFuture(_:file:line:)

Extension method

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


                    
                    
                    makeSucceededFuture(_:file:line:)

Extension method

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


                    
                    
                    scheduleRepeatedTask(initialDelay:delay:notifying:_:)

Extension method

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

return: RepeatedTask

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


                    
                    
                    scheduleRepeatedAsyncTask(initialDelay:delay:notifying:_:)

Extension method

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. 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
assertInEventLoop(file:line:) Extension method
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
assertNotInEventLoop(file:line:) Extension method
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