EventLoop
public protocol EventLoop : EventLoopGroup
An EventLoop processes IO / tasks in an endless loop for Channel
s until it’s closed.
Usually multiple Channel
s 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 Channel
s 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 currentNIOThread
is the same as theNIOThread
that is tied to thisEventLoop
.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 returnedEventLoopFuture
is notified.Default Implementation
Submit
task
to be run on thisEventLoop
.The returned
EventLoopFuture
will be completed whentask
has finished running. It will be succeeded withtask
‘s return value or failed if the execution oftask
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 thisEventLoop
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. -
Schedule a
task
that is executed by thisEventLoop
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. -
preconditionInEventLoop(file:
Default implementationline: ) Asserts that the current thread is the one tied to this
EventLoop
. Otherwise, the process will be abnormally terminated as per the semantics ofpreconditionFailure(_: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)
-
preconditionNotInEventLoop(file:
Default implementationline: ) Asserts that the current thread is not the one tied to this
EventLoop
. Otherwise, the process will be abnormally terminated as per the semantics ofpreconditionFailure(_: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)
-
flatSubmit(_:
Extension method) Submit
task
to be run on thisEventLoop
.The returned
EventLoopFuture
will be completed whentask
has finished running. It will be identical to theEventLoopFuture
returned bytask
.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 theEventLooopFuture
returned fromtask
. -
flatScheduleTask(deadline:
Extension methodfile: line: _: ) Schedule a
task
that is executed by thisEventLoop
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 returnedEventLoopFuture
. -
flatScheduleTask(in:
Extension methodfile: line: _: ) Schedule a
task
that is executed by thisEventLoop
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 returnedEventLoopFuture
. -
makePromise(of:
Extension methodfile: line: ) Creates and returns a new
EventLoopPromise
that will be notified using thisEventLoop
as executionNIOThread
.Declaration
Swift
@inlinable public func makePromise<T>(of type: T.Type = T.self, file: StaticString = #file, line: UInt = #line) -> EventLoopPromise<T>
-
makeFailedFuture(_:
Extension methodfile: line: ) Creates and returns a new
EventLoopFuture
that is already marked as failed. Notifications will be done using thisEventLoop
as executionNIOThread
.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 theEventLoopFuture
.Return Value
a failed
EventLoopFuture
. -
makeSucceededFuture(_:
Extension methodfile: line: ) Creates and returns a new
EventLoopFuture
that is already marked as success. Notifications will be done using thisEventLoop
as executionNIOThread
.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 methodAn
EventLoop
forms a singularEventLoopGroup
, returning itself as the ‘next’EventLoop
.Declaration
Swift
public func next() -> EventLoop
Return Value
Itself, because an
EventLoop
forms a singularEventLoopGroup
. -
close()
Extension methodClose this
EventLoop
.Declaration
Swift
public func close() throws
-
scheduleRepeatedTask(initialDelay:
Extension methoddelay: notifying: _: ) 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.
- return:
-
scheduleRepeatedAsyncTask(initialDelay:
Extension methoddelay: notifying: _: ) 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.
-
makeIterator()
Extension methodReturns an
EventLoopIterator
over thisEventLoop
.Declaration
Swift
public func makeIterator() -> EventLoopIterator
Return Value
-
assertInEventLoop(file:
Extension methodline: ) 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 ofpreconditionFailure(_: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)
-
assertNotInEventLoop(file:
Extension methodline: ) 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 ofpreconditionFailure(_: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)