Merge pull request #850 from apple/ahoppen/asyncification

Migrate huge chunks of sourcekit-lsp to actors/async/await

Author: ahoppen

Sources/LSPLogging/Logging.swift

@@ -62,6 +62,22 @@ public func orLog<R>(
   }
 }
 
+/// Like `try?`, but logs the error on failure.
+public func orLog<R>(
+  _ prefix: String = "",
+  level: LogLevel = .default,
+  logger: Logger = Logger.shared,
+  _ block: () async throws -> R?) async -> R?
+{
+  do {
+    return try await block()
+  } catch {
+    logger.log("\(prefix)\(prefix.isEmpty ? "" : " ")\(error)", level: level)
+    return nil
+  }
+}
+
+
 /// Logs the time that the given block takes to execute in milliseconds.
 public func logExecutionTime<R>(
   _ prefix: String = #function,

Sources/LSPTestSupport/AssertNoThrow.swift

@@ -0,0 +1,105 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import XCTest
+
+/// Same as `assertNoThrow` but executes the trailing closure.
+public func assertNoThrow<T>(
+  _ expression: () throws -> T,
+  _ message: @autoclosure () -> String = "",
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  XCTAssertNoThrow(try expression(), message(), file: file, line: line)
+}
+
+/// Same as `XCTAssertThrows` but executes the trailing closure.
+public func assertThrowsError<T>(
+  _ expression: @autoclosure () async throws -> T,
+  _ message: @autoclosure () -> String = "",
+  file: StaticString = #filePath,
+  line: UInt = #line,
+  _ errorHandler: (_ error: Error) -> Void = { _ in }
+) async {
+  let didThrow: Bool
+  do {
+    _ = try await expression()
+    didThrow = false
+  } catch {
+    errorHandler(error)
+    didThrow = true
+  }
+  if !didThrow {
+    XCTFail("Expression was expected to throw but did not throw", file: file, line: line)
+  }
+}
+
+/// Same as `XCTAssertEqual` but doesn't take autoclosures and thus `expression1`
+/// and `expression2` can contain `await`.
+public func assertEqual<T: Equatable>(
+  _ expression1: T,
+  _ expression2: T,
+  _ message: @autoclosure () -> String = "",
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  XCTAssertEqual(expression1, expression2, message(), file: file, line: line)
+}
+
+/// Same as `XCTAssertNil` but doesn't take autoclosures and thus `expression`
+/// can contain `await`.
+public func assertNil<T: Equatable>(
+  _ expression: T?,
+  _ message: @autoclosure () -> String = "",
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  XCTAssertNil(expression, message(), file: file, line: line)
+}
+
+/// Same as `XCTAssertNotNil` but doesn't take autoclosures and thus `expression`
+/// can contain `await`.
+public func assertNotNil<T: Equatable>(
+  _ expression: T?,
+  _ message: @autoclosure () -> String = "",
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  XCTAssertNotNil(expression, message(), file: file, line: line)
+}
+
+extension XCTestCase {
+  private struct ExpectationNotFulfilledError: Error, CustomStringConvertible {
+    var expecatations: [XCTestExpectation]
+
+    var description: String {
+      return "One of the expectation was not fulfilled within timeout: \(expecatations.map(\.description).joined(separator: ", "))"
+    }
+  }
+
+  /// Wait for the given expectations to be fulfilled. If the expectations aren't 
+  /// fulfilled within `timeout`, throw an error, aborting the test execution.
+  public func fulfillmentOfOrThrow(
+    _ expectations: [XCTestExpectation],
+    timeout: TimeInterval = defaultTimeout,
+    enforceOrder enforceOrderOfFulfillment: Bool = false
+  ) async throws {
+    // `XCTWaiter.fulfillment` was introduced in the macOS 13.3 SDK but marked as being available on macOS 10.15.
+    // At the same time that XCTWaiter.fulfillment was introduced `XCTWaiter.wait` was deprecated in async contexts.
+    // This means that we can't write code that compiles without warnings with both the macOS 13.3 and any previous SDK.
+    // Accepting the warning here when compiling with macOS 13.3 or later is the only thing that I know of that we can do here.
+    let started = XCTWaiter.wait(for: expectations, timeout: timeout, enforceOrder: enforceOrderOfFulfillment)
+    if started != .completed {
+      throw ExpectationNotFulfilledError(expecatations: expectations)
+    }
+  }
+}

Sources/LSPTestSupport/Assertions.swift

@@ -0,0 +1,127 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+/// Abstraction layer so we can store a heterogeneous collection of tasks in an
+/// array.
+private protocol AnyTask: Sendable {
+  func waitForCompletion() async
+}
+
+extension Task: AnyTask where Failure == Never {
+  func waitForCompletion() async {
+    _ = await value
+  }
+}
+
+extension NSLock {
+  /// NOTE: Keep in sync with SwiftPM's 'Sources/Basics/NSLock+Extensions.swift'
+  func withLock<T>(_ body: () throws -> T) rethrows -> T {
+    lock()
+    defer { unlock() }
+    return try body()
+  }
+}
+
+/// A queue that allows the execution of asyncronous blocks of code.
+public final class AsyncQueue {
+  public enum QueueKind {
+    /// A queue that allows concurrent execution of tasks.
+    case concurrent
+
+    /// A queue that executes one task after the other.
+    case serial
+  }
+
+  private struct PendingTask {
+    /// The task that is pending.
+    let task: any AnyTask
+
+    /// Whether the task needs to finish executing befoer any other task can
+    /// start in executing in the queue.
+    let isBarrier: Bool
+
+    /// A unique value used to identify the task. This allows tasks to get
+    /// removed from `pendingTasks` again after they finished executing.
+    let id: UUID
+  }
+
+  /// Whether the queue allows concurrent execution of tasks.
+  private let kind: QueueKind
+
+  ///  Lock guarding `pendingTasks`.
+  private let pendingTasksLock = NSLock()
+
+  /// Pending tasks that have not finished execution yet.
+  private var pendingTasks = [PendingTask]()
+
+  public init(_ kind: QueueKind) {
+    self.kind = kind
+    self.pendingTasksLock.name = "AsyncQueue"
+  }
+
+  /// Schedule a new closure to be executed on the queue.
+  ///
+  /// If this is a serial queue, all previously added tasks are guaranteed to
+  /// finished executing before this closure gets executed.
+  ///
+  /// If this is a barrier, all previously scheduled tasks are guaranteed to
+  /// finish execution before the barrier is executed and all tasks that are
+  /// added later will wait until the barrier finishes execution.
+  @discardableResult
+  public func async<Success: Sendable>(
+    priority: TaskPriority? = nil,
+    barrier isBarrier: Bool = false,
+    @_inheritActorContext operation: @escaping @Sendable () async -> Success
+  ) -> Task<Success, Never> {
+    let id = UUID()
+
+    return pendingTasksLock.withLock {
+      // Build the list of tasks that need to finishe exeuction before this one
+      // can be executed
+      let dependencies: [PendingTask]
+      switch (kind, isBarrier: isBarrier) {
+      case (.concurrent, isBarrier: true):
+        // Wait for all tasks after the last barrier.
+        let lastBarrierIndex = pendingTasks.lastIndex(where: { $0.isBarrier }) ?? pendingTasks.startIndex
+        dependencies = Array(pendingTasks[lastBarrierIndex...])
+      case (.concurrent, isBarrier: false):
+        // If there is a barrier, wait for it.
+        dependencies = [pendingTasks.last(where: { $0.isBarrier })].compactMap { $0 }
+      case (.serial, _):
+        // We are in a serial queue. The last pending task must finish for this one to start.
+        dependencies = [pendingTasks.last].compactMap { $0 }
+      }
+
+
+      // Schedule the task.
+      let task = Task {
+        for dependency in dependencies {
+          await dependency.task.waitForCompletion()
+        }
+
+        let result = await operation()
+
+        pendingTasksLock.withLock {
+          pendingTasks.removeAll(where: { $0.id == id })
+        }
+
+        return result
+      }
+
+      pendingTasks.append(PendingTask(task: task, isBarrier: isBarrier, id: id))
+
+      return task
+    }
+  }
+}

Sources/LanguageServerProtocol/AsyncQueue.swift

@@ -1,4 +1,5 @@
 add_library(LanguageServerProtocol STATIC
+  AsyncQueue.swift
   Cancellation.swift
   Connection.swift
   CustomCodable.swift

Sources/LanguageServerProtocol/CMakeLists.txt

@@ -42,9 +42,18 @@ extension Connection {
 public protocol MessageHandler: AnyObject {
 
   /// Handle a notification without a reply.
+  ///
+  /// The method should return as soon as the notification has been sufficiently
+  /// handled to avoid out-of-order requests, e.g. once the notification has
+  /// been forwarded to clangd.
   func handle(_ params: some NotificationType, from clientID: ObjectIdentifier)
 
   /// Handle a request and (asynchronously) receive a reply.
+  ///
+  /// The method should return as soon as the request has been sufficiently
+  /// handled to avoid out-of-order requests, e.g. once the corresponding
+  /// request has been sent to sourcekitd. The actual semantic computation
+  /// should occur after the method returns and report the result via `reply`.
   func handle<Request: RequestType>(_ params: Request, id: RequestID, from clientID: ObjectIdentifier, reply: @escaping (LSPResult<Request.Response>) -> Void)
 }
 
@@ -66,8 +75,9 @@ public final class LocalConnection {
     case ready, started, closed
   }
 
+  /// The queue guarding `_nextRequestID`.
   let queue: DispatchQueue = DispatchQueue(label: "local-connection-queue")
-
+  
   var _nextRequestID: Int = 0
 
   var state: State = .ready
@@ -104,22 +114,30 @@ public final class LocalConnection {
 
 extension LocalConnection: Connection {
   public func send<Notification>(_ notification: Notification) where Notification: NotificationType {
-    handler?.handle(notification, from: ObjectIdentifier(self))
+    self.handler?.handle(notification, from: ObjectIdentifier(self))
   }
 
-  public func send<Request>(_ request: Request, queue: DispatchQueue, reply: @escaping (LSPResult<Request.Response>) -> Void) -> RequestID where Request: RequestType {
+  public func send<Request: RequestType>(
+    _ request: Request,
+    queue: DispatchQueue,
+    reply: @escaping (LSPResult<Request.Response>) -> Void
+  ) -> RequestID {
     let id = nextRequestID()
-    guard let handler = handler else {
-      queue.async { reply(.failure(.serverCancelled)) }
+
+    guard let handler = self.handler else {
+      queue.async {
+        reply(.failure(.serverCancelled))
+      }
       return id
     }
 
-    precondition(state == .started)
+    precondition(self.state == .started)
     handler.handle(request, id: id, from: ObjectIdentifier(self)) { result in
       queue.async {
         reply(result)
       }
     }
+
     return id
   }
 }

Sources/LanguageServerProtocol/Connection.swift

@@ -11,7 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 public typealias CodeActionProviderCompletion = (LSPResult<[CodeAction]>) -> Void
-public typealias CodeActionProvider = (CodeActionRequest, @escaping CodeActionProviderCompletion) -> Void
+public typealias CodeActionProvider = (CodeActionRequest, @escaping CodeActionProviderCompletion) async -> Void
 
 /// Request for returning all possible code actions for a given text document and range.
 ///