TaskLocal

Overview 概要

A task-local value is a value that can be bound and read in the context of a Task. It is implicitly carried with the task, and is accessible by any child tasks the task creates (such as TaskGroup or async let created tasks). タスクローカルな値は、あるTaskの文脈においてバインド（束縛）および読み出しされることが可能な値です。それは暗黙的にそのタスクとともに運搬されます、そしてそのタスクが作成するあらゆる子タスクによってアクセス可能です（たとえば TaskGroup または async let が作成したタスク）。

Task-local declarations タスクローカルな宣言

Task locals must be declared as static properties (or global properties, once property wrappers support these), like this: タスクローカルそれらは、静的プロパティとして宣言されなければなりません（またはグローバルプロパティ、一旦プロパティラッパーがそれらをサポートするならば）、このように：

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

Default values 省略時の値

Task local values of optional types default to nil. It is possible to define not-optional task-local values, and an explicit default value must then be defined instead. オプショナル型のタスクローカル値は、省略時にはnilになります。非オプショナルのタスクローカル値を定義するのは可能です、そしてある明示的な省略時の値がそのとき代わりに定義されなければなりません。

The default value is returned whenever the task-local is read from a context which either: has no task available to read the value from (e.g. a synchronous function, called without any asynchronous function in its call stack), 省略時の値は、タスクローカル値がこのどちらかの文脈で読み出される時はいつでも返されます：値をそれから読み出すのに利用可能なタスクがひとつもない（たとえば、それの呼び出しスタックの中にどんな非同期関数もなしに呼び出されるある同期関数）、

Reading task-local values タスクローカル値を読み出す

Reading task local values is simple and looks the same as-if reading a normal static property: タスクローカル値の読み出しは簡単です、そして通常の静的プロパティを読み出す場合と同じに見えます：

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

It is possible to perform task-local value reads from either asynchronous or synchronous functions. Within asynchronous functions, as a “current” task is always guaranteed to exist, this will perform the lookup in the task local context. タスクローカル値の読み出しを非同期または同期関数のどちらかから実行することは可能です。非同期関数の内側では、“現在の” タスクは常に存在することを保証されます、これはタスクローカル文脈における検索を実行するでしょう。

A lookup made from the context of a synchronous function, that is not called from an asynchronous function (!), will immediately return the task-local’s default value. 同期関数の文脈から作られた検索は、それは非同期関数から呼び出されません（！）、直ぐにタスクローカルのもつ省略時の値を返すでしょう。

Binding task-local values タスクローカル値のバインド（束縛）

Task local values cannot be set directly and must instead be bound using the scoped $traceID.withValue() { ... } operation. The value is only bound for the duration of that scope, and is available to any child tasks which are created within that scope. タスクローカル値は、直接にsetされることが出来ません、そして代わりにスコープ付き$traceID.withValue() { ... }演算を使ってバインドされなければなりません。値は、そのスコープの持続期間に対してバインドされるだけです、そしてそのスコープ内で作成されたすべての子タスクに利用可能です。

Detached tasks do not inherit task-local values, however tasks created using the Task { ... } initializer do inherit task-locals by copying them to the new asynchronous task, even though it is an un-structured task. 分離されたタスクは、タスクローカル値を継承しません、しかしながらTask { ... }イニシャライザを使って作成されたタスクは、タスクローカルをそれらを新しい非同期タスクにコビーすることによって継承します、たとえそれが構造化されないタスクであっても。

Examples 例

@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
}

This type must be a class so it has a stable identity, that is used as key value for lookups in the task local storage. この型は、classでなければなりません、なのでそれは安定した同一性を持ちます、それはタスクローカルストレージにおける検索それらに対するキー値として使われます。