Improve the names of a few commonly used APIs (#2014)

Motivation:

Naming is important; it should be clear and concise.

Modifications:

The follow renames all offer more precise names:
- Rename `server.run()` to `server.serve()`
- Rename `server.stopListening()` to `server.beginGracefulShutdown()`
- Rename `client.close()` to `client.beginGracefulShutdown()`

Result:

Clearer APIs

Examples/v2/echo/Subcommands/Collect.swift

@@ -53,7 +53,7 @@ struct Collect: AsyncParsableCommand {
         print("collect ← \(message.text)")
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/echo/Subcommands/Expand.swift

@@ -53,7 +53,7 @@ struct Expand: AsyncParsableCommand {
         }
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/echo/Subcommands/Get.swift

@@ -48,7 +48,7 @@ struct Get: AsyncParsableCommand {
         print("get ← \(response.text)")
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/echo/Subcommands/Serve.swift

@@ -36,7 +36,7 @@ struct Serve: AsyncParsableCommand {
     )
 
     try await withThrowingDiscardingTaskGroup { group in
-      group.addTask { try await server.run() }
+      group.addTask { try await server.serve() }
       if let address = try await server.listeningAddress {
         print("Echo listening on \(address)")
       }

Examples/v2/echo/Subcommands/Update.swift

@@ -56,7 +56,7 @@ struct Update: AsyncParsableCommand {
         }
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/hello-world/Subcommands/Greet.swift

@@ -42,7 +42,7 @@ struct Greet: AsyncParsableCommand {
       }
 
       defer {
-        client.close()
+        client.beginGracefulShutdown()
       }
 
       let greeter = Helloworld_GreeterClient(wrapping: client)

Examples/v2/hello-world/Subcommands/Serve.swift

@@ -35,7 +35,7 @@ struct Serve: AsyncParsableCommand {
     )
 
     try await withThrowingDiscardingTaskGroup { group in
-      group.addTask { try await server.run() }
+      group.addTask { try await server.serve() }
       if let address = try await server.listeningAddress {
         print("Greeter listening on \(address)")
       }

Examples/v2/route-guide/Subcommands/GetFeature.swift

@@ -63,7 +63,7 @@ struct GetFeature: AsyncParsableCommand {
         print("Found '\(feature.name)' at (\(self.latitude), \(self.longitude))")
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/route-guide/Subcommands/ListFeatures.swift

@@ -79,7 +79,7 @@ struct ListFeatures: AsyncParsableCommand {
         }
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
 
   }

Examples/v2/route-guide/Subcommands/RecordRoute.swift

@@ -68,7 +68,7 @@ struct RecordRoute: AsyncParsableCommand {
         """
       print(text)
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/route-guide/Subcommands/RouteChat.swift

@@ -68,7 +68,7 @@ struct RouteChat: AsyncParsableCommand {
         }
       }
 
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 }

Examples/v2/route-guide/Subcommands/Serve.swift

@@ -45,7 +45,7 @@ struct Serve: AsyncParsableCommand {
 
     let server = GRPCServer(transport: transport, services: [RouteGuideService(features: features)])
     try await withThrowingDiscardingTaskGroup { group in
-      group.addTask { try await server.run() }
+      group.addTask { try await server.serve() }
       let address = try await transport.listeningAddress
       print("server listening on \(address)")
     }

Sources/GRPCCore/Documentation.docc/Tutorials/Route-Guide/Resources/route-guide-sec05-step08-run.swift

@@ -14,7 +14,7 @@ extension RouteGuide {
 
     try await withThrowingTaskGroup(of: Void.self) { group in
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       if let address = try await server.listeningAddress {

Sources/GRPCCore/GRPCClient.swift

@@ -99,12 +99,12 @@ internal import Atomics
 ///   }
 ///
 ///   // The RPC has completed, close the client.
-///   client.close()
+///   client.beginGracefulShutdown()
 /// }
 /// ```
 ///
 /// The ``run()`` method won't return until the client has finished handling all requests. You can
-/// signal to the client that it should stop creating new request streams by calling ``close()``.
+/// signal to the client that it should stop creating new request streams by calling ``beginGracefulShutdown()``.
 /// This gives the client enough time to drain any requests already in flight. To stop the client
 /// more abruptly you can cancel the task running your client. If your application requires
 /// additional resources that need their lifecycles managed you should consider using [Swift Service
@@ -159,7 +159,7 @@ public struct GRPCClient: Sendable {
 
   /// Start the client.
   ///
-  /// This returns once ``close()`` has been called and all in-flight RPCs have finished executing.
+  /// This returns once ``beginGracefulShutdown()`` has been called and all in-flight RPCs have finished executing.
   /// If you need to abruptly stop all work you should cancel the task executing this method.
   ///
   /// The client, and by extension this function, can only be run once. If the client is already
@@ -210,7 +210,7 @@ public struct GRPCClient: Sendable {
   /// The transport will be closed: this means that it will be given enough time to wait for
   /// in-flight RPCs to finish executing, but no new RPCs will be accepted. You can cancel the task
   /// executing ``run()`` if you want to abruptly stop in-flight RPCs.
-  public func close() {
+  public func beginGracefulShutdown() {
     while true {
       let (wasRunning, actualState) = self.state.compareExchange(
         expected: .running,
@@ -220,7 +220,7 @@ public struct GRPCClient: Sendable {
 
       // Transition from running to stopping: close the transport.
       if wasRunning {
-        self.transport.close()
+        self.transport.beginGracefulShutdown()
         return
       }
 
@@ -351,7 +351,7 @@ public struct GRPCClient: Sendable {
 
   /// Start a bidirectional streaming RPC.
   ///
-  /// - Note: ``run()`` must have been called and still executing, and ``close()`` mustn't
+  /// - Note: ``run()`` must have been called and still executing, and ``beginGracefulShutdown()`` mustn't
   /// have been called.
   ///
   /// - Parameters:

Sources/GRPCCore/GRPCServer.swift

@@ -60,11 +60,11 @@ internal import Atomics
 ///
 /// ```swift
 /// // Start running the server.
-/// try await server.run()
+/// try await server.serve()
 /// ```
 ///
 /// The ``run()`` method won't return until the server has finished handling all requests. You can
-/// signal to the server that it should stop accepting new requests by calling ``stopListening()``.
+/// signal to the server that it should stop accepting new requests by calling ``beginGracefulShutdown()``.
 /// This allows the server to drain existing requests gracefully. To stop the server more abruptly
 /// you can cancel the task running your server. If your application requires additional resources
 /// that need their lifecycles managed you should consider using [Swift Service
@@ -154,13 +154,13 @@ public struct GRPCServer: Sendable {
   ///
   /// This function returns when the configured transport has stopped listening and all requests have been
   /// handled. You can signal to the transport that it should stop listening by calling
-  /// ``stopListening()``. The server will continue to process existing requests.
+  /// ``beginGracefulShutdown()``. The server will continue to process existing requests.
   ///
   /// To stop the server more abruptly you can cancel the task that this function is running in.
   ///
   /// - Note: You can only call this function once, repeated calls will result in a
   ///   ``RuntimeError`` being thrown.
-  public func run() async throws {
+  public func serve() async throws {
     let (wasNotStarted, actualState) = self.state.compareExchange(
       expected: .notStarted,
       desired: .running,
@@ -209,7 +209,7 @@ public struct GRPCServer: Sendable {
   /// against this server. Once the server has processed all requests the ``run()`` method returns.
   ///
   /// Calling this on a server which is already stopping or has stopped has no effect.
-  public func stopListening() {
+  public func beginGracefulShutdown() {
     let (wasRunning, actual) = self.state.compareExchange(
       expected: .running,
       desired: .stopping,
@@ -217,7 +217,7 @@ public struct GRPCServer: Sendable {
     )
 
     if wasRunning {
-      self.transport.stopListening()
+      self.transport.beginGracefulShutdown()
     } else {
       switch actual {
       case .notStarted:
@@ -229,7 +229,7 @@ public struct GRPCServer: Sendable {
 
         // Lost a race with 'run()', try again.
         if !exchanged {
-          self.stopListening()
+          self.beginGracefulShutdown()
         }
 
       case .running:

Sources/GRPCCore/Transport/ClientTransport.swift

@@ -34,7 +34,7 @@ public protocol ClientTransport: Sendable {
   ///
   /// Implementations of this function will typically create a long-lived task group which
   /// maintains connections. The function exits when all open streams have been closed and new connections
-  /// are no longer required by the caller who signals this by calling ``close()``, or by cancelling the
+  /// are no longer required by the caller who signals this by calling ``beginGracefulShutdown()``, or by cancelling the
   /// task this function runs in.
   func connect() async throws
 
@@ -46,7 +46,7 @@ public protocol ClientTransport: Sendable {
   ///
   /// If you want to forcefully cancel all active streams then cancel the task
   /// running ``connect()``.
-  func close()
+  func beginGracefulShutdown()
 
   /// Opens a stream using the transport, and uses it as input into a user-provided closure.
   ///

Sources/GRPCCore/Transport/ServerTransport.swift

@@ -26,7 +26,7 @@ public protocol ServerTransport: Sendable {
   /// and start accepting new connections. Each accepted inbound RPC stream will be handed over to
   /// the provided `streamHandler` to handle accordingly.
   ///
-  /// You can call ``stopListening()`` to stop the transport from accepting new streams. Existing
+  /// You can call ``beginGracefulShutdown()`` to stop the transport from accepting new streams. Existing
   /// streams must be allowed to complete naturally. However, transports may also enforce a grace
   /// period after which any open streams may be cancelled. You can also cancel the task running
   /// ``listen(_:)`` to abruptly close connections and streams.
@@ -38,5 +38,5 @@ public protocol ServerTransport: Sendable {
   ///
   /// Existing streams are permitted to run to completion. However, the transport may also enforce
   /// a grace period, after which remaining streams are cancelled.
-  func stopListening()
+  func beginGracefulShutdown()
 }

Sources/GRPCHTTP2Core/Client/Connection/GRPCChannel.swift

@@ -138,9 +138,9 @@ package final class GRPCChannel: ClientTransport {
             for try await result in self.resolver.names {
               self.input.continuation.yield(.handleResolutionResult(result))
             }
-            self.close()
+            self.beginGracefulShutdown()
           } catch {
-            self.close()
+            self.beginGracefulShutdown()
           }
         }
 
@@ -183,7 +183,7 @@ package final class GRPCChannel: ClientTransport {
 
   /// Signal to the transport that no new streams may be created and that connections should be
   /// closed when all streams are closed.
-  package func close() {
+  package func beginGracefulShutdown() {
     self.input.continuation.yield(.close)
   }
 
@@ -393,7 +393,7 @@ extension GRPCChannel {
       self.updateLoadBalancer(serviceConfig: config, endpoints: result.endpoints, in: &group)
 
     case .failure:
-      self.close()
+      self.beginGracefulShutdown()
     }
   }
 
@@ -567,10 +567,10 @@ extension GRPCChannel {
       if let result = try await iterator.next() {
         self.handleNameResolutionResult(result, in: &group)
       } else {
-        self.close()
+        self.beginGracefulShutdown()
       }
     } catch {
-      self.close()
+      self.beginGracefulShutdown()
     }
   }
 }

Sources/GRPCHTTP2TransportNIOPosix/HTTP2ClientTransport+Posix.swift

@@ -105,8 +105,8 @@ extension HTTP2ClientTransport {
       self.channel.configuration(forMethod: descriptor)
     }
 
-    public func close() {
-      self.channel.close()
+    public func beginGracefulShutdown() {
+      self.channel.beginGracefulShutdown()
     }
 
     public func withStream<T: Sendable>(

Sources/GRPCHTTP2TransportNIOPosix/HTTP2ServerTransport+Posix.swift

@@ -328,7 +328,7 @@ extension HTTP2ServerTransport {
       }
     }
 
-    public func stopListening() {
+    public func beginGracefulShutdown() {
       self.serverQuiescingHelper.initiateShutdown(promise: nil)
     }
   }

Sources/GRPCHTTP2TransportNIOTransportServices/HTTP2ServerTransport+TransportServices.swift

@@ -280,7 +280,7 @@ extension HTTP2ServerTransport {
       }
     }
 
-    public func stopListening() {
+    public func beginGracefulShutdown() {
       self.serverQuiescingHelper.initiateShutdown(promise: nil)
     }
   }

Sources/GRPCInProcessTransport/InProcessClientTransport.swift

@@ -190,7 +190,7 @@ public final class InProcessClientTransport: ClientTransport {
   /// will result in an ``RPCError`` with code ``RPCError/Code/failedPrecondition`` being thrown.
   ///
   /// If you want to forcefully cancel all active streams then cancel the task running ``connect()``.
-  public func close() {
+  public func beginGracefulShutdown() {
     let maybeContinuation: AsyncStream<Void>.Continuation? = self.state.withLock { state in
       switch state {
       case .unconnected:

Sources/GRPCInProcessTransport/InProcessServerTransport.swift

@@ -23,7 +23,7 @@ public import GRPCCore
 ///
 /// To use this server, you call ``listen(_:)`` and iterate over the returned `AsyncSequence` to get all
 /// RPC requests made from clients (as ``RPCStream``s).
-/// To stop listening to new requests, call ``stopListening()``.
+/// To stop listening to new requests, call ``beginGracefulShutdown()``.
 ///
 /// - SeeAlso: ``ClientTransport``
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
@@ -44,7 +44,7 @@ public struct InProcessServerTransport: ServerTransport, Sendable {
   ///
   /// - Parameter stream: The new ``RPCStream`` to publish.
   /// - Throws: ``RPCError`` with code ``RPCError/Code-swift.struct/failedPrecondition``
-  /// if the server transport stopped listening to new streams (i.e., if ``stopListening()`` has been called).
+  /// if the server transport stopped listening to new streams (i.e., if ``beginGracefulShutdown()`` has been called).
   internal func acceptStream(_ stream: RPCStream<Inbound, Outbound>) throws {
     let yieldResult = self.newStreamsContinuation.yield(stream)
     if case .terminated = yieldResult {
@@ -70,7 +70,7 @@ public struct InProcessServerTransport: ServerTransport, Sendable {
   /// Stop listening to any new ``RPCStream`` publications.
   ///
   /// - SeeAlso: ``ServerTransport``
-  public func stopListening() {
+  public func beginGracefulShutdown() {
     self.newStreamsContinuation.finish()
   }
 }

Sources/interoperability-tests/InteroperabilityTestsExecutable.swift

@@ -47,7 +47,7 @@ struct InteroperabilityTestsExecutable: AsyncParsableCommand {
         ),
         services: [TestService()]
       )
-      try await server.run()
+      try await server.serve()
     }
   }
 
@@ -97,7 +97,7 @@ struct InteroperabilityTestsExecutable: AsyncParsableCommand {
           await self.runTest(testCase, using: client)
         }
 
-        client.close()
+        client.beginGracefulShutdown()
       }
     }
 

Sources/performance-worker/BenchmarkClient.swift

@@ -120,7 +120,7 @@ struct BenchmarkClient {
         try await rpcsGroup.waitForAll()
       }
 
-      self.client.close()
+      self.client.beginGracefulShutdown()
       try await clientGroup.next()
     }
   }
@@ -237,6 +237,6 @@ struct BenchmarkClient {
 
   internal func shutdown() {
     self._isShuttingDown.store(true, ordering: .relaxed)
-    self.client.close()
+    self.client.beginGracefulShutdown()
   }
 }

Sources/performance-worker/PerformanceWorker.swift

@@ -57,7 +57,7 @@ struct PerformanceWorker: AsyncParsableCommand {
       ),
       services: [WorkerService()]
     )
-    try await server.run()
+    try await server.serve()
   }
 }
 

Sources/performance-worker/WorkerService.swift

@@ -239,7 +239,7 @@ extension WorkerService: Grpc_Testing_WorkerService.ServiceProtocol {
       }
 
     case .shutDownServer(let server):
-      server.stopListening()
+      server.beginGracefulShutdown()
     }
 
     return ServerResponse.Single(message: Grpc_Testing_Void())
@@ -269,7 +269,7 @@ extension WorkerService: Grpc_Testing_WorkerService.ServiceProtocol {
               let result: Result<Void, any Error>
 
               do {
-                try await server.run()
+                try await server.serve()
                 result = .success(())
               } catch {
                 result = .failure(error)
@@ -317,7 +317,7 @@ extension WorkerService: Grpc_Testing_WorkerService.ServiceProtocol {
         // shutdown its ELG.
         switch self.state.withLockedValue({ $0.stopListening() }) {
         case .stopListening(let server):
-          server.stopListening()
+          server.beginGracefulShutdown()
         case .nothing:
           ()
         }
@@ -409,7 +409,7 @@ extension WorkerService {
     case .runServer:
       return (server, transport)
     case .invalidState(let error):
-      server.stopListening()
+      server.beginGracefulShutdown()
       try await eventLoopGroup.shutdownGracefully()
       throw error
     }

Tests/GRPCCoreTests/Call/Client/Internal/ClientRPCExecutorTestSupport/ClientRPCExecutorTestHarness.swift

@@ -143,8 +143,8 @@ struct ClientRPCExecutorTestHarness {
       )
 
       // Close the client so the server can finish.
-      self.clientTransport.close()
-      self.serverTransport.stopListening()
+      self.clientTransport.beginGracefulShutdown()
+      self.serverTransport.beginGracefulShutdown()
       group.cancelAll()
     }
   }

Tests/GRPCCoreTests/GRPCClientTests.swift

@@ -31,7 +31,7 @@ final class GRPCClientTests: XCTestCase {
 
     try await withThrowingTaskGroup(of: Void.self) { group in
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       group.addTask {
@@ -41,8 +41,8 @@ final class GRPCClientTests: XCTestCase {
       // Make sure both server and client are running
       try await Task.sleep(for: .milliseconds(100))
       try await body(client, server)
-      client.close()
-      server.stopListening()
+      client.beginGracefulShutdown()
+      server.beginGracefulShutdown()
     }
   }
 
@@ -273,7 +273,7 @@ final class GRPCClientTests: XCTestCase {
       }
 
       // New RPCs should fail immediately after this.
-      client.close()
+      client.beginGracefulShutdown()
 
       // RPC should fail now.
       await XCTAssertThrowsErrorAsync(ofType: RuntimeError.self) {
@@ -296,7 +296,7 @@ final class GRPCClientTests: XCTestCase {
         request: .init(producer: { writer in
 
           // Close the client once this RCP has been started.
-          client.close()
+          client.beginGracefulShutdown()
 
           // Attempts to start a new RPC should fail.
           await XCTAssertThrowsErrorAsync(ofType: RuntimeError.self) {
@@ -335,7 +335,7 @@ final class GRPCClientTests: XCTestCase {
     try await withThrowingTaskGroup(of: Void.self) { group in
       group.addTask {
         let server = GRPCServer(transport: inProcess.server, services: [BinaryEcho()])
-        try await server.run()
+        try await server.serve()
       }
 
       group.addTask {

Tests/GRPCCoreTests/GRPCServerTests.swift

@@ -34,7 +34,7 @@ final class GRPCServerTests: XCTestCase {
 
     try await withThrowingTaskGroup(of: Void.self) { group in
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       group.addTask {
@@ -42,8 +42,8 @@ final class GRPCServerTests: XCTestCase {
       }
 
       try await body(inProcess.client, server)
-      inProcess.client.close()
-      server.stopListening()
+      inProcess.client.beginGracefulShutdown()
+      server.beginGracefulShutdown()
     }
   }
 
@@ -274,7 +274,7 @@ final class GRPCServerTests: XCTestCase {
       try await self.doEchoGet(using: client)
 
       // New streams should fail immediately after this.
-      server.stopListening()
+      server.beginGracefulShutdown()
 
       // RPC should fail now.
       await XCTAssertThrowsRPCErrorAsync {
@@ -303,7 +303,7 @@ final class GRPCServerTests: XCTestCase {
         XCTAssertMetadata(metadata)
 
         // New streams should fail immediately after this.
-        server.stopListening()
+        server.beginGracefulShutdown()
 
         try await stream.outbound.write(.message([0]))
         stream.outbound.finish()
@@ -320,7 +320,7 @@ final class GRPCServerTests: XCTestCase {
     let inProcess = InProcessTransport.makePair()
     let task = Task {
       let server = GRPCServer(transport: inProcess.server, services: [BinaryEcho()])
-      try await server.run()
+      try await server.serve()
     }
 
     try await withThrowingTaskGroup(of: Void.self) { group in
@@ -340,13 +340,13 @@ final class GRPCServerTests: XCTestCase {
   func testTestRunStoppedServer() async throws {
     let server = GRPCServer(transport: InProcessServerTransport(), services: [])
     // Run the server.
-    let task = Task { try await server.run() }
+    let task = Task { try await server.serve() }
     task.cancel()
     try await task.value
 
     // Server is stopped, should throw an error.
     await XCTAssertThrowsErrorAsync(ofType: RuntimeError.self) {
-      try await server.run()
+      try await server.serve()
     } errorHandler: { error in
       XCTAssertEqual(error.code, .serverIsStopped)
     }
@@ -355,7 +355,7 @@ final class GRPCServerTests: XCTestCase {
   func testRunServerWhenTransportThrows() async throws {
     let server = GRPCServer(transport: ThrowOnRunServerTransport(), services: [])
     await XCTAssertThrowsErrorAsync(ofType: RuntimeError.self) {
-      try await server.run()
+      try await server.serve()
     } errorHandler: { error in
       XCTAssertEqual(error.code, .transportError)
     }

Tests/GRPCCoreTests/Test Utilities/Transport/AnyTransport.swift

@@ -45,7 +45,7 @@ struct AnyClientTransport: ClientTransport, Sendable {
     }
 
     self._close = {
-      transport.close()
+      transport.beginGracefulShutdown()
     }
 
     self._configuration = { descriptor in
@@ -61,7 +61,7 @@ struct AnyClientTransport: ClientTransport, Sendable {
     try await self._connect()
   }
 
-  func close() {
+  func beginGracefulShutdown() {
     self._close()
   }
 
@@ -94,7 +94,7 @@ struct AnyServerTransport: ServerTransport, Sendable {
 
   init<Transport: ServerTransport>(wrapping transport: Transport) {
     self._listen = { streamHandler in try await transport.listen(streamHandler) }
-    self._stopListening = { transport.stopListening() }
+    self._stopListening = { transport.beginGracefulShutdown() }
   }
 
   func listen(
@@ -103,7 +103,7 @@ struct AnyServerTransport: ServerTransport, Sendable {
     try await self._listen(streamHandler)
   }
 
-  func stopListening() {
+  func beginGracefulShutdown() {
     self._stopListening()
   }
 }

Tests/GRPCCoreTests/Test Utilities/Transport/StreamCountingTransport.swift

@@ -47,8 +47,8 @@ struct StreamCountingClientTransport: ClientTransport, Sendable {
     try await self.transport.connect()
   }
 
-  func close() {
-    self.transport.close()
+  func beginGracefulShutdown() {
+    self.transport.beginGracefulShutdown()
   }
 
   func withStream<T>(
@@ -102,7 +102,7 @@ struct StreamCountingServerTransport: ServerTransport, Sendable {
     }
   }
 
-  func stopListening() {
-    self.transport.stopListening()
+  func beginGracefulShutdown() {
+    self.transport.beginGracefulShutdown()
   }
 }

Tests/GRPCCoreTests/Test Utilities/Transport/ThrowingTransport.swift

@@ -32,7 +32,7 @@ struct ThrowOnStreamCreationTransport: ClientTransport {
     // no-op
   }
 
-  func close() {
+  func beginGracefulShutdown() {
     // no-op
   }
 
@@ -60,7 +60,7 @@ struct ThrowOnRunServerTransport: ServerTransport {
     )
   }
 
-  func stopListening() {
+  func beginGracefulShutdown() {
     // no-op
   }
 }
@@ -84,7 +84,7 @@ struct ThrowOnSignalServerTransport: ServerTransport {
     )
   }
 
-  func stopListening() {
+  func beginGracefulShutdown() {
     // no-op
   }
 }

Tests/GRPCHTTP2CoreTests/Client/Connection/GRPCChannelTests.swift

@@ -96,7 +96,7 @@ final class GRPCChannelTests: XCTestCase {
           XCTAssertEqual(throttle.tokenRatio, 0.1)
 
           // Now close.
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -176,7 +176,7 @@ final class GRPCChannelTests: XCTestCase {
             return noConfigForGet && configForUpdate && noThrottle
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -362,7 +362,7 @@ final class GRPCChannelTests: XCTestCase {
         switch part1 {
         case .metadata:
           // Got metadata, close the channel.
-          channel.close()
+          channel.beginGracefulShutdown()
         case .message, .status, .none:
           XCTFail("Expected metadata, got \(String(describing: part1))")
         }
@@ -472,7 +472,7 @@ final class GRPCChannelTests: XCTestCase {
 
           // All RPCs done, close the channel and cancel the group to stop the server.
           if outstandingRPCs == 0 {
-            channel.close()
+            channel.beginGracefulShutdown()
             group.cancelAll()
           }
 
@@ -537,7 +537,7 @@ final class GRPCChannelTests: XCTestCase {
 
           // All RPCs done, close the channel and cancel the group to stop the server.
           if outstandingRPCs == 0 {
-            channel.close()
+            channel.beginGracefulShutdown()
             group.cancelAll()
           }
 
@@ -616,7 +616,7 @@ final class GRPCChannelTests: XCTestCase {
             server1.clients.count == 0 && server2.clients.count == 0 && server3.clients.count == 1
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         case .shutdown:
           group.cancelAll()
@@ -683,7 +683,7 @@ final class GRPCChannelTests: XCTestCase {
                 break
               }
             }
-            channel.close()
+            channel.beginGracefulShutdown()
           default:
             ()
           }
@@ -737,7 +737,7 @@ final class GRPCChannelTests: XCTestCase {
             server1.clients.count == 1 && server2.clients.count == 0
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -776,7 +776,7 @@ final class GRPCChannelTests: XCTestCase {
             // Sleep a little to increase the chances of the stream being queued before the channel
             // reacts to the close.
             try await Task.sleep(for: .milliseconds(10))
-            channel.close()
+            channel.beginGracefulShutdown()
           }
 
           // Try to open a new stream.

Tests/GRPCHTTP2TransportTests/HTTP2TransportNIOPosixTests.swift

@@ -40,7 +40,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv4Address = try XCTUnwrap(address.ipv4)
         XCTAssertNotEqual(ipv4Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -60,7 +60,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv6Address = try XCTUnwrap(address.ipv6)
         XCTAssertNotEqual(ipv6Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -82,7 +82,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
           address.unixDomainSocket,
           GRPCHTTP2Core.SocketAddress.UnixDomainSocket(path: "/tmp/posix-uds-test")
         )
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -103,7 +103,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.virtualSocket)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -165,7 +165,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.ipv4)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }

Tests/GRPCHTTP2TransportTests/HTTP2TransportNIOTransportServicesTests.swift

@@ -37,7 +37,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv4Address = try XCTUnwrap(address.ipv4)
         XCTAssertNotEqual(ipv4Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -57,7 +57,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv6Address = try XCTUnwrap(address.ipv6)
         XCTAssertNotEqual(ipv6Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -83,7 +83,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
           address.unixDomainSocket,
           GRPCHTTP2Core.SocketAddress.UnixDomainSocket(path: "/tmp/niots-uds-test")
         )
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -145,7 +145,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.ipv4)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }

Tests/GRPCHTTP2TransportTests/HTTP2TransportTests.swift

@@ -94,8 +94,8 @@ final class HTTP2TransportTests: XCTestCase {
           XCTFail("Unexpected error: '\(error)' (\(pair))")
         }
 
-        server.stopListening()
-        client.close()
+        server.beginGracefulShutdown()
+        client.beginGracefulShutdown()
       }
     }
   }
@@ -155,7 +155,7 @@ final class HTTP2TransportTests: XCTestCase {
       )
 
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       let address = try await server.listeningAddress!
@@ -174,7 +174,7 @@ final class HTTP2TransportTests: XCTestCase {
       )
 
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       let address = try await server.listeningAddress!

Tests/GRPCInProcessTransportTests/InProcessClientTransportTests.swift

@@ -46,7 +46,7 @@ final class InProcessClientTransportTests: XCTestCase {
   func testConnectWhenClosed() async {
     let client = makeClient()
 
-    client.close()
+    client.beginGracefulShutdown()
 
     await XCTAssertThrowsErrorAsync(ofType: RPCError.self) {
       try await client.connect()
@@ -80,14 +80,14 @@ final class InProcessClientTransportTests: XCTestCase {
   func testCloseWhenUnconnected() {
     let client = makeClient()
 
-    XCTAssertNoThrow(client.close())
+    XCTAssertNoThrow(client.beginGracefulShutdown())
   }
 
   func testCloseWhenClosed() {
     let client = makeClient()
-    client.close()
+    client.beginGracefulShutdown()
 
-    XCTAssertNoThrow(client.close())
+    XCTAssertNoThrow(client.beginGracefulShutdown())
   }
 
   func testConnectSuccessfullyAndThenClose() async throws {
@@ -102,7 +102,7 @@ final class InProcessClientTransportTests: XCTestCase {
       }
 
       try await group.next()
-      client.close()
+      client.beginGracefulShutdown()
     }
   }
 
@@ -118,7 +118,7 @@ final class InProcessClientTransportTests: XCTestCase {
           // Once the pending stream is opened, close the client to new connections,
           // so that, once this closure is executed and this stream is closed,
           // the client will return from `connect()`.
-          client.close()
+          client.beginGracefulShutdown()
         }
       }
 
@@ -136,7 +136,7 @@ final class InProcessClientTransportTests: XCTestCase {
   func testOpenStreamWhenClosed() async {
     let client = makeClient()
 
-    client.close()
+    client.beginGracefulShutdown()
 
     await XCTAssertThrowsErrorAsync(ofType: RPCError.self) {
       try await client.withStream(
@@ -182,7 +182,7 @@ final class InProcessClientTransportTests: XCTestCase {
 
       group.addTask {
         try await Task.sleep(for: .milliseconds(100))
-        client.close()
+        client.beginGracefulShutdown()
       }
 
       try await group.next()
@@ -277,7 +277,7 @@ final class InProcessClientTransportTests: XCTestCase {
 
       group.addTask {
         try await Task.sleep(for: .milliseconds(50))
-        client.close()
+        client.beginGracefulShutdown()
       }
 
       try await group.next()

Tests/GRPCInProcessTransportTests/InProcessServerTransportTests.swift

@@ -44,7 +44,7 @@ final class InProcessServerTransportTests: XCTestCase {
         try await transport.listen { stream in
           let partValue = try? await stream.inbound.reduce(into: []) { $0.append($1) }
           XCTAssertEqual(partValue, [.message([42])])
-          transport.stopListening()
+          transport.beginGracefulShutdown()
         }
       }
 
@@ -77,7 +77,7 @@ final class InProcessServerTransportTests: XCTestCase {
       }
       XCTAssertEqual(firstStreamMessages, [.message([42])])
 
-      transport.stopListening()
+      transport.beginGracefulShutdown()
 
       let secondStreamOutbound = AsyncThrowingStream.makeStream(of: RPCResponsePart.self)
       let secondStream = RPCStream<

Tests/InProcessInteroperabilityTests/InProcessInteroperabilityTests.swift

@@ -29,7 +29,7 @@ final class InProcessInteroperabilityTests: XCTestCase {
       try await withThrowingTaskGroup(of: Void.self) { group in
         group.addTask {
           let server = GRPCServer(transport: inProcess.server, services: [TestService()])
-          try await server.run()
+          try await server.serve()
         }
 
         group.addTask {

Tests/Services/HealthTests/HealthTests.swift

@@ -31,7 +31,7 @@ final class HealthTests: XCTestCase {
 
     try await withThrowingDiscardingTaskGroup { group in
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       group.addTask {