Swift TaskLocal用法及代碼示例

TaskLocal

概述

task-local 值是可以在 Task 的上下文中綁定和讀取的值。它隱含在任務中，可由任務創建的任何子任務(例如TaskGroup 或async let 創建的任務)訪問。

Task-local 聲明

任務局部變量必須聲明為靜態屬性(或全局屬性，一旦屬性包裝器支持這些)，如下所示：

enum TracingExample {
    @TaskLocal
    static let traceID: TraceID?
}

默認值

可選類型的任務本地值默認為 nil 。可以定義 not-optional task-local 值，然後必須定義顯式默認值。

每當從以下任一上下文中讀取 task-local 時都會返回默認值： 沒有可用於讀取值的任務(例如，同步函數，在其調用堆棧中沒有任何異步函數的情況下調用)，

讀取 task-local 值

讀取任務本地值很簡單，看起來與讀取普通靜態屬性的 as-if 相同：

guard let traceID = TracingExample.traceID else {
  print("no trace id")
  return
}
print(traceID)

可以從異步或同步函數執行 task-local 值讀取。在異步函數中，由於始終保證 “current” 任務存在，這將在任務本地上下文中執行查找。

從同步函數的上下文中進行的查找，而不是從異步函數 (!) 調用，將立即返回 task-local 的默認值。

綁定 task-local 值

任務本地值不能直接為set，而必須使用作用域$traceID.withValue() { ... } 操作綁定。該值僅在該範圍內綁定，並且可用於在該範圍內創建的任何子任務。

分離的任務不繼承 task-local 值，但是使用 Task { ... } 初始化程序創建的任務通過將它們複製到新的異步任務來繼承 task-locals，即使它是 un-structured 任務。

例子

@TaskLocal
static var traceID: TraceID?


print("traceID: \(traceID)") // traceID: nil


$traceID.withValue(1234) { // bind the value
  print("traceID: \(traceID)") // traceID: 1234
  call() // traceID: 1234


  Task { // unstructured tasks do inherit task locals by copying
    call() // traceID: 1234
  }


  Task.detached { // detached tasks do not inherit task-local values
    call() // traceID: nil
  }
}


func call() {
  print("traceID: \(traceID)") // 1234
}

此類型必須是class，因此它具有穩定的標識，用作任務本地存儲中查找的鍵值。