I have recently spent the last couple of weeks with a few folks at Apple thinking about how we might offer async/await APIs for this project. Specifically how users might be able to implement and call gRPC services using APIs that abstract away NIO and expose functionality in terms of the new native Swift concurrency features.

I have written up our thinking so far in the form of a proposal which is contained in this PR with the hope of gathering feedback from a wider audience. Anyone who has feedback should feel welcome to comment directly on the contents of this PR.

I also have a branch that implements the proposal for those who wish to take a closer look at how it looks and feels: https://github.com/grpc/grpc-swift/compare/main...simonjbeaumont:async-await-poc-squashed.

Thanks to @glbrntt for the help so far!

/cc @glbrntt @Lukasa @fabianfett

Ah... I see I broke the api breakage pipeline. I didn't realise this underscore module was intended to be API stable at this point. Should I leave the original one in (that returns void) and add a completely separate one with a fixit?

I confess that I put this together with a specific calendar server. It worked there and on the one used by my current employer but that's a small sample size so maybe I overlooked some nuance.

Would you mind elaborating on the circumstances this can happen?

Regardless, should we consider printing something else when there is no CN? Even if that ends up being a placeholder like <unknown>.

I take it tzlocal is a package you have installed locally?

Unfortunately that will mean this line adds a new python package dependency.

However, from a quick search it looks like Python has builtin support for astimezone.

I'm also in favour taking a patch that will render the calendar invite in the user's timezone if we can do so with builtin library calls. If that means explicitly using Python 3 then that's fine, so long as we update the shebang at the top. Also would want to make sure that we render a suffix on the end of the timestamp so the user knew the timezone that is being used. I'd be happy with either the letter abbreviation (e.g. PST) or an offset (e.g. -08:00).

//cc @glbrntt

Return Task from EventLoopPromise.completeWithAsync(_:) wrapper.

Motivation:

Bridging an async function into NIO is done by calling completeWithAsync(_ body:) on an EventLoopPromise. This spins up a Task and awaits the result of the async closure that was passed in and uses the result to fulfil the promise with the value of the function, if it was successful, or with the error, if the function threw.

In some cases we may want to cancel this operation from the outside.

Modifications:

This patch adds a discardable return value to EventLoopPromise.completeWithAsync(_:) which is the Task it creates.

Result:

Users of EventLoopPromise.completeWithAsync(_:) are now able to explicitly cancel the Task that is being used to fulfil the promise.

Lemme add the shutdown to the catch.

Yes, I noticed this.

I wasn't able able to use the defer shutdown with the async, and because the comments said it was safe to call shutdown twice, I thought the safest thing to do was to leave the top-level shutdown.

I'll move the group lifecycle into the async function, though as it's probably the right thing to do.

Adds a new extension to EventLoopGroup in _NIOConcurrency to provide an asynchronous shutdownGracefully().

Motivation

Shutting down an event loop was special because it used a completion handler and executed on a DispatchQueue because there would be no event loop to use an EventLoopFuture.

Now we have the new Swift concurrency features, we can provide an async shutdownGracefully.

Fixes #1878.

Modifications

Adds EventLoopGroup.shutdownGracefully() async and some code to use it in NIOAsyncAwaitDemo.

There's no obvious way to ask an ELG if it has been shutdown but I made the following local-only changes to verify that this performs as expected:

diff --git a/Sources/NIO/EventLoop.swift b/Sources/NIO/EventLoop.swift
index d18a33dd..972b3b05 100644
--- a/Sources/NIO/EventLoop.swift
+++ b/Sources/NIO/EventLoop.swift
@@ -840 +840 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup {
-    private enum RunState {
+    public enum RunState {
@@ -852 +852 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup {
-    private var runState: RunState = .running
+    public var runState: RunState = .running
diff --git a/Sources/NIOAsyncAwaitDemo/main.swift b/Sources/NIOAsyncAwaitDemo/main.swift
index 97a9c0c3..f8b29ace 100644
--- a/Sources/NIOAsyncAwaitDemo/main.swift
+++ b/Sources/NIOAsyncAwaitDemo/main.swift
@@ -60,0 +61 @@ func main() async {
+        print("elg state: \(group.runState)")  // .running
@@ -61,0 +63,7 @@ func main() async {
+        print("elg state: \(group.runState)")  // .closed(nil)
+
+        /// This causes the following error:
+        /// ERROR: Cannot schedule tasks on an EventLoop that has already shut down. This will be upgraded to a forced crash in future SwiftNIO versions.
+        group.next().execute {
+            print("This will not execute.")
+        }