A task local key declaration nested under in the `TaskLocalValues` and consists  > This design may remind you of SwiftUI's `@Environment` concept, and indeed the shape of how values are declared is fairly similar. However, it differs tremendously in *where* the child/parent relationship is expressed. In a later section we'll make a more detailed comparison with SwiftUI. -Next, in order to access the value one has to `await Task.local(_:)` it:+Next, in order to access the value one has to `Task.local(_:)` it:  ```swift-func printRequestID() async {-  let id = await Task.local(\.requestID) ?? "<unknown>"+func asyncPrintRequestID() async {+  let id = Task.local(\.requestID)   print("request-id: \(id)") }-``` -Since it is not known statically if the value will be present or not, the returned value is an `Optional<String>`.+func syncPrintRequestID() async {

+# Task Local Values++* Proposal: [SE-NNNN](NNNN-task-local.md)+* Authors: [Konrad 'ktoso' Malawski](https://github.com/ktoso)+* Review Manager: TBD+* Status: Awaiting review+* Implementation: [apple/swift#34722](https://github.com/apple/swift/pull/34722)++## Table of Contents++* [Introduction](#introduction)+* [Motivation](#motivation)+* [Proposed solution](#proposed-solution)+  * [Task Local Values](#task-local-values-1)+* [Detailed design](#detailed-design)+  * [Declaring task-local values](#declaring-task-local-values)+  * [Binding task-local values](#binding-task-local-values)+    * [Binding values for the duration of a child-task](#binding-values-for-the-duration-of-a-child-task)+  * [Task-local value lifecycle](#task-local-value-lifecycle)+  * [Reading task-local values](#reading-task-local-values)+    * [Reading task-local values: implementation details](#reading-task-local-values-implementation-details)+  * [Similarities and differences with SwiftUI Environment](#similarities-and-differences-with-swiftui-environment)+* [Prior Art](#prior-art)+  * [Kotlin: CoroutineContext[T]](#kotlin-coroutinecontextt)+  * [Java/Loom: Scope Variables](#javaloom-scope-variables)+  * [Go: explicit context passing all the way](#go-explicit-context-passing-all-the-way)+* [Rejected Alternatives](#rejected-alternatives)+  * [Plain-old Thread Local variables](#plain-old-thread-local-variables)+  * [Dispatch Queue Specific Values](#dispatch-queue-specific-values)+* [Intended use-cases](#intended-use-cases)+  * [Use case: Distributed Tracing &amp; Contextual Logging](#use-case-distributed-tracing--contextual-logging)+    * [Contextual Logging](#contextual-logging)+    * [Function Tracing](#function-tracing)+    * [Distributed Tracing](#distributed-tracing)+    * [Future direction: Function wrapper interaction](#future-direction-function-wrapper-interaction)+  * [Use case: Mocking internals (Swift System)](#use-case-mocking-internals-swift-system)+  * [Use case: Progress Monitoring](#use-case-progress-monitoring)+  * [Use case: Executor configuration](#use-case-executor-configuration)+* [Future Directions](#future-directions)+  * [Tracing annotations with Function Wrappers](#tracing-annotations-with-function-wrappers)+* [Revision history](#revision-history)+* [Source compatibility](#source-compatibility)+* [Effect on ABI stability](#effect-on-abi-stability)+* [Effect on API resilience](#effect-on-api-resilience)++## Introduction++With Swift embracing asynchronous functions and actors, asynchronous code will be everywhere. ++Therefore, the need for debugging, tracing and otherwise instrumenting asynchronous code becomes even more necessary than before. At the same time, tools which instrumentation systems could have used before to carry information along requests -- such as thread locals or queue-specific values -- are no longer compatible with Swift's Task-focused take on concurrency.++Previously, tool developers could have relied on thread-local or queue-specific values as containers to associate information with a task and carry it across suspension boundaries. However, these mechanisms do not compose well in general, have known "gotchas" (e.g., forgetting to carefully maintain and clear state from these containers after a task has completed to avoid leaking them), and do not compose at all with Swift's task-first approach to concurrency. Furthermore, those mechanisms do not feel "right" given Swift's focus on Structured Concurrency, because they are inherently unstructured.++This proposal defines the semantics of _Task Local Values_. That is, values which are local to a `Task`.++Task local values set in a task _cannot_ out-live the task, solving many of the pain points relating to un-structured primitives such as thread-locals, as well as aligning this feature closely with Swift's take on Structured Concurrency.++Swift-evolution thread: [Discussion thread topic for that proposal](https://forums.swift.org/t/pitch-task-local-values/42829/15)++## Motivation++Task Local Values are a significant improvement over thread-local storage in that it is a better fit for Swift's concurrency model because it takes advantage of its structured nature. In existing code, developers have used thread-local or queue-specific values to associate state with each thread/queue, however the exact semantics of those mechanisms made it difficult and error prone in reality.++Specifically, previously developers could have used thread-local or queue-specific values to achieve some of these features, however the exact semantics of those made it difficult and error prone in reality. ++> The use of thread-locals in highly asynchronous libraries is generally frowned upon because it is so difficult to get right, and generally only adds to the confusion rather than helping one achieve transparent context propagation. +> +> This is why currently [Swift Distributed Tracing](https://github.com/apple/swift-distributed-tracing) had to revert to using explicit context passing, making asynchronous APIs even more verbose than they already are.+++Finally, those mechanisms are outright incompatible with asynchronous code that hops between execution contexts, which also includes Swift's async/await execution semantics which guarantee specific _executors_ or _actors_ to be used for execution, however never guarantees any specific queue or thread use at all.++> For discussion about alternative approaches to this problem please refer to [Prior Art](#prior-art) and [Alternatives Considered](#alternatives-considered).++## Proposed solution++### Task Local Values++Tasks already require the capability to "carry metadata with them," and that metadata used to implement both cancellation, deadlines as well as priority propagation for a `Task` and its child tasks. Specifically Task API's exhibiting similar behavior are: `Task.currentPriority()`, `Task.currentDeadline()` and `Task.isCancelled()`. Task local values do not directly use the same storage mechanism, as cancellation and priority is somewhat optimized because _all_ tasks carry them, but the semantics are the same.++We propose to expose the Task's internal ability to "carry metadata with it" via a Swift API, *aimed for library and instrumentation authors* such that they can participate in carrying additional information with Tasks, the same way as Tasks already do with priority and deadlines and other metadata.++Task local values may only be accessed from contexts that are running in a task: asynchronous functions. As such all operations, except declaring the task-local value's handle are asynchronous operations.++Declaring a task local value begins with declaring a `TaskLocalKey` that will be used to retrieve it from the task:++```swift+extension TaskLocalValues {+  +    public struct RequestIDKey: TaskLocalKey {+      public static var defaultValue: String { "<no-request-id>" } +      +      // alternatively, one may declare a nil default value:+      //     public static var defaultValue: String? { nil } +    }+    public var requestID: RequestIDKey { .init() }+  +}+```++A task local key declaration nested under in the `TaskLocalValues` and consists of two things:++- a `TaskLocalKey` type declaration, where the `defaultValue`'s type is used to infer the type of the task local value+  - depending on the value, one might opt for declaring the type as `Optional` or not, for example if a good "empty" default value exists for the type+- a computed property `requestID` which returning the key - it is only used to lookup the key, and no set operation is necessary for it (unlike in SwiftUI's Environment model, due to differences in how the values are actually looked up). ++> This design may remind you of SwiftUI's `@Environment` concept, and indeed the shape of how values are declared is fairly similar. However, it differs tremendously in *where* the child/parent relationship is expressed. In a later section we'll make a more detailed comparison with SwiftUI.++Next, in order to access the value one has to `Task.local(_:)` it:++```swift+func asyncPrintRequestID() async {+  let id = Task.local(\.requestID)+  print("request-id: \(id)")+}++func syncPrintRequestID() async {

 struct TextEditor { } ``` +### Extending property wrappers to patterns++Property-wrapper backing-storage initialization in the the pattern of a closure argument was supported in first revision. Building on this syntax, the core team suggested the extension of property-wrapper application to places where patterns exist. Of course, the design has been amended so as to preserve the expectation that the backing storage be private; extending property wrappers to patterns, though, is still a viable future direction. ++Enabling the application of property wrappers where patterns are available is quite straightforward and could be introduced in as part of two separate features. The first could be to enable utility wrappers –– such as `@Asserted` –– in patterns. The second could be enabling projected-value initialization, which would facilitate intuitive and effortless access to property wrappers in native language constructs, as shown below:

 struct TextEditor { } ``` +### Extending property wrappers to patterns++Property-wrapper backing-storage initialization in the the pattern of a closure argument was supported in first revision. Building on this syntax, the core team suggested the extension of property-wrapper application to places where patterns exist. Of course, the design has been amended so as to preserve the expectation that the backing storage be private; extending property wrappers to patterns, though, is still a viable future direction. ++Enabling the application of property wrappers where patterns are available is quite straightforward and could be introduced in as part of two separate features. The first could be to enable utility wrappers –– such as `@Asserted` –– in patterns. The second could be enabling projected-value initialization, which would facilitate intuitive and effortless access to property wrappers in native language constructs, as shown below:

 internal extension JSONSerialization {         return .utf8     }     -    static func parseBOM(_ bytes: UnsafePointer<UInt8>, length: Int) -> (encoding: String.Encoding, skipLength: Int)? {-        if length >= 2 {-            switch (bytes[0], bytes[1]) {-            case (0xEF, 0xBB):-                if length >= 3 && bytes[2] == 0xBF {-                    return (.utf8, 3)-                }-            case (0x00, 0x00):-                if length >= 4 && bytes[2] == 0xFE && bytes[3] == 0xFF {-                    return (.utf32BigEndian, 4)-                }-            case (0xFF, 0xFE):-                if length >= 4 && bytes[2] == 0 && bytes[3] == 0 {-                    return (.utf32LittleEndian, 4)-                }-                return (.utf16LittleEndian, 2)-            case (0xFE, 0xFF):-                return (.utf16BigEndian, 2)-            default:-                break+    static func parseBOM(_ bytes: UnsafeRawBufferPointer) -> (encoding: String.Encoding, skipLength: Int)? {+        guard bytes.count >= 2 else {

 A task local key declaration nested under in the `TaskLocalValues` and consists  > This design may remind you of SwiftUI's `@Environment` concept, and indeed the shape of how values are declared is fairly similar. However, it differs tremendously in *where* the child/parent relationship is expressed. In a later section we'll make a more detailed comparison with SwiftUI. -Next, in order to access the value one has to `await Task.local(_:)` it:+Next, in order to access the value one has to `Task.local(_:)` it:  ```swift-func printRequestID() async {-  let id = await Task.local(\.requestID) ?? "<unknown>"+func asyncPrintRequestID() async {+  let id = Task.local(\.requestID)   print("request-id: \(id)") }-``` -Since it is not known statically if the value will be present or not, the returned value is an `Optional<String>`.+func syncPrintRequestID() async {

 open class UserDefaults: NSObject {             return true         }         -        let isOfCommonTypes =  value is String || value is Data || value is Date || value is Int || value is Bool || value is CGFloat+        let isOfCommonTypes = value is String || value is Data || value is Date || value is Int || value is Bool || value is CGFloat

 struct TextEditor { } ``` +### Extending property wrappers to patterns++Property-wrapper backing-storage initialization in the the pattern of a closure argument was supported in first revision. Building on this syntax, the core team suggested the extension of property-wrapper application to places where patterns exist. Of course, the design has been amended so as to preserve the expectation that the backing storage be private; extending property wrappers to patterns, though, is still a viable future direction. ++Enabling the application of property wrappers where patterns are available is quite straightforward and could be introduced in as part of two separate features. The first could be to enable utility wrappers –– such as `@Asserted` –– in patterns. The second could be enabling projected-value initialization, which would facilitate intuitive and effortless access to property wrappers in native language constructs, as shown below: