Improve the names of a few commonly used 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,15 +209,15 @@ 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,
       ordering: .sequentiallyConsistent
     )
 
     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()
       }
     }