From 848e42899027d1b47219bf513cf771fcfd14e4eb Mon Sep 17 00:00:00 2001
From: Johannes Weiss <johannesweiss@apple.com>
Date: Mon, 25 Nov 2024 18:15:18 +0000
Subject: [PATCH] deprecate NIOEventLoopGroupProvider.createNew (#2480)

### Motivation:

`NIOEventLoopGroupProvider.createNew` was probably never a good idea
because it creates shutdown issues for any library that uses it. Given
that we now have singleton (#2471) `EventLoopGroup`s, we can solve this
issue by just not having event loop group providers.

Users can just use `group: any EventLoopGroup` and optionally `group:
any EventLoopGroup = MultiThreadedEventLoopGroup.singleton`.

### Modifications:

- deprecate `NIOEventLoopGroupProvider.createNew`
- soft-deprecate (document as deprecated but don't mark
`@available(deprecated)`) `NIOEventLoopGroupProvider`

### Result:

- Libraries becomes easier to write and maintain.
- Fixes #2142
---
 Sources/NIOCore/Docs.docc/index.md |  1 -
 Sources/NIOCore/EventLoop.swift    | 21 +++++++++++++++++++--
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/Sources/NIOCore/Docs.docc/index.md b/Sources/NIOCore/Docs.docc/index.md
index 13d76894ec..5b437b073e 100644
--- a/Sources/NIOCore/Docs.docc/index.md
+++ b/Sources/NIOCore/Docs.docc/index.md
@@ -21,7 +21,6 @@ More specialized modules provide concrete implementations of many of the abstrac
 
 - ``EventLoopGroup``
 - ``EventLoop``
-- ``NIOEventLoopGroupProvider``
 - ``EventLoopIterator``
 - ``Scheduled``
 - ``RepeatedTask``
diff --git a/Sources/NIOCore/EventLoop.swift b/Sources/NIOCore/EventLoop.swift
index 047c06e67e..376f06d8fb 100644
--- a/Sources/NIOCore/EventLoop.swift
+++ b/Sources/NIOCore/EventLoop.swift
@@ -1246,16 +1246,33 @@ extension EventLoopGroup {
 }
 #endif
 
-/// This type is intended to be used by libraries which use NIO, and offer their users either the option
+/// Deprecated.
+///
+/// This type was intended to be used by libraries which use NIO, and offer their users either the option
 /// to `.share` an existing event loop group or create (and manage) a new one (`.createNew`) and let it be
 /// managed by given library and its lifecycle.
+///
+/// Please use a `group: any EventLoopGroup` parameter instead. If you want to default to a global
+/// singleton group instead, consider group: any EventLoopGroup = MultiThreadedEventLoopGroup.singleton` or
+/// similar.
+///
+/// - See also: https://github.com/apple/swift-nio/issues/2142
 public enum NIOEventLoopGroupProvider {
     /// Use an `EventLoopGroup` provided by the user.
     /// The owner of this group is responsible for its lifecycle.
     case shared(EventLoopGroup)
-    /// Create a new `EventLoopGroup` when necessary.
+
+    /// Deprecated. Create a new `EventLoopGroup` when necessary.
     /// The library which accepts this provider takes ownership of the created event loop group,
     /// and must ensure its proper shutdown when the library is being shut down.
+    @available(
+        *,
+        deprecated,
+        message: """
+            Please use `.shared(existingGroup)` or use the singleton via \
+            `.shared(MultiThreadedEventLoopGroup.singleton)` or similar
+            """
+    )
     case createNew
 }