2626/// }
2727///
2828/// While defining a key, one should also immediately declare an extension on `ServiceContext` to allow convenient and discoverable ways to interact
29- /// with the baggage item. The extension should take the form of:
29+ /// with the context item. The extension should take the form of:
3030///
3131/// extension ServiceContext {
3232/// var testID: String? {
4343/// Swift naming conventions, e.g. prefer `ID` to `Id` etc.
4444///
4545/// ## Usage
46- /// Using a baggage container is fairly straight forward, as it boils down to using the prepared computed properties:
46+ /// Using a context container is fairly straight forward, as it boils down to using the prepared computed properties:
4747///
48- /// var baggage = ServiceContext.topLevel
48+ /// var context = ServiceContext.topLevel
4949/// // set a new value
50- /// baggage .testID = "abc"
50+ /// context .testID = "abc"
5151/// // retrieve a stored value
52- /// let testID = baggage .testID ?? "default"
52+ /// let testID = context .testID ?? "default"
5353/// // remove a stored value
54- /// baggage .testIDKey = nil
54+ /// context .testIDKey = nil
5555///
56- /// Note that normally a baggage should not be "created" ad-hoc by user code, but rather it should be passed to it from
56+ /// Note that normally a context should not be "created" ad-hoc by user code, but rather it should be passed to it from
5757/// a runtime. A `ServiceContext` may already be available to you through ServiceContext.$current when using structured concurrency.
58- /// Otherwise, for example when working in an HTTP server framework, it is most likely that the baggage is already passed
58+ /// Otherwise, for example when working in an HTTP server framework, it is most likely that the context is already passed
5959/// directly or indirectly (e.g. in a `FrameworkContext`).
6060///
6161/// ### Accessing all values
6262///
63- /// The only way to access "all" values in a baggage is by using the `forEach` function.
63+ /// The only way to access "all" values in a context is by using the `forEach` function.
6464/// `ServiceContext` does not expose more functions on purpose to prevent abuse and treating it as too much of an
6565/// arbitrary value smuggling container, but only make it convenient for tracing and instrumentation systems which need
66- /// to access either specific or all items carried inside a baggage .
66+ /// to access either specific or all items carried inside a context .
6767public struct ServiceContext : Sendable {
6868 private var _storage = [ AnyServiceContextKey: Sendable] ( )
6969
70- /// Internal on purpose, please use ``ServiceContext/TODO(_:function:file:line:)`` or ``ServiceContext/topLevel`` to create an "empty" baggage ,
71- /// which carries more meaning to other developers why an empty baggage was used.
70+ /// Internal on purpose, please use ``ServiceContext/TODO(_:function:file:line:)`` or ``ServiceContext/topLevel`` to create an "empty" context ,
71+ /// which carries more meaning to other developers why an empty context was used.
7272 init ( ) { }
7373}
7474
7575// MARK: - Creating ServiceContext
7676
7777extension ServiceContext {
78- /// Creates a new empty "top level" baggage , generally used as an "initial" baggage to immediately be populated with
78+ /// Creates a new empty "top level" context , generally used as an "initial" context to immediately be populated with
7979 /// some values by a framework or runtime. Another use case is for tasks starting in the "background" (e.g. on a timer),
8080 /// which don't have a "request context" per se that they can pick up, and as such they have to create a "top level"
81- /// baggage for their work.
81+ /// context for their work.
8282 ///
8383 /// ## Usage in frameworks and libraries
8484 /// This function is really only intended to be used by frameworks and libraries, at the "top-level" where a request's,
8585 /// message's or task's processing is initiated. For example, a framework handling requests, should create an empty
86- /// baggage when handling a request only to immediately populate it with useful trace information extracted from e.g.
86+ /// context when handling a request only to immediately populate it with useful trace information extracted from e.g.
8787 /// request headers.
8888 ///
8989 /// ## Usage in applications
90- /// Application code should never have to create an empty baggage during the processing lifetime of any request,
91- /// and only should create baggage if some processing is performed in the background - thus the naming of this property.
90+ /// Application code should never have to create an empty context during the processing lifetime of any request,
91+ /// and only should create context if some processing is performed in the background - thus the naming of this property.
9292 ///
9393 /// Usually, a framework such as an HTTP server or similar "request handler" would already provide users
9494 /// with a context to be passed along through subsequent calls, either implicitly through the task-local `ServiceContext.$current`
9595 /// or explicitly as part of some kind of "FrameworkContext".
9696 ///
97- /// If unsure where to obtain a baggage from, prefer using `.TODO("Not sure where I should get a context from here?")`
98- /// in order to inform other developers that the lack of baggage passing was not done on purpose, but rather because either
99- /// not being sure where to obtain a baggage from, or other framework limitations -- e.g. the outer framework not being
100- /// baggage aware just yet.
97+ /// If unsure where to obtain a context from, prefer using `.TODO("Not sure where I should get a context from here?")`
98+ /// in order to inform other developers that the lack of context passing was not done on purpose, but rather because either
99+ /// not being sure where to obtain a context from, or other framework limitations -- e.g. the outer framework not being
100+ /// context aware just yet.
101101 public static var topLevel : ServiceContext {
102102 ServiceContext ( )
103103 }
104104}
105105
106106extension ServiceContext {
107- /// A baggage intended as a placeholder until a real value can be passed through a function call.
107+ /// A context intended as a placeholder until a real value can be passed through a function call.
108108 ///
109- /// It should ONLY be used while prototyping or when the passing of the proper baggage is not yet possible,
110- /// e.g. because an external library did not pass it correctly and has to be fixed before the proper baggage
109+ /// It should ONLY be used while prototyping or when the passing of the proper context is not yet possible,
110+ /// e.g. because an external library did not pass it correctly and has to be fixed before the proper context
111111 /// can be obtained where the TO-DO is currently used.
112112 ///
113113 /// ## Crashing on TO-DO context creation
114- /// You may set the `BAGGAGE_CRASH_TODOS ` variable while compiling a project in order to make calls to this function crash
115- /// with a fatal error, indicating where a to-do baggage was used. This comes in handy when wanting to ensure that
116- /// a project never ends up using code which initially was written as "was lazy, did not pass baggage ", yet the
117- /// project requires baggage passing to be done correctly throughout the application. Similar checks can be performed
114+ /// You may set the `SERVICE_CONTEXT_CRASH_TODOS ` variable while compiling a project in order to make calls to this function crash
115+ /// with a fatal error, indicating where a to-do context was used. This comes in handy when wanting to ensure that
116+ /// a project never ends up using code which initially was written as "was lazy, did not pass context ", yet the
117+ /// project requires context passing to be done correctly throughout the application. Similar checks can be performed
118118 /// at compile time easily using linters (not yet implemented), since it is always valid enough to detect a to-do context
119119 /// being passed as illegal and warn or error when spotted.
120120 ///
121121 /// ## Example
122122 ///
123- /// let baggage = ServiceContext.TODO("The framework XYZ should be modified to pass us a baggage here, and we'd pass it along"))
123+ /// let context = ServiceContext.TODO("The framework XYZ should be modified to pass us a context here, and we'd pass it along"))
124124 ///
125125 /// - Parameters:
126126 /// - reason: Informational reason for developers, why a placeholder context was used instead of a proper one,
127127 /// - function: The function to which the TODO refers.
128128 /// - file: The file to which the TODO refers.
129129 /// - line: The line to which the TODO refers.
130- /// - Returns: Empty "to-do" baggage which should be eventually replaced with a carried through one, or `topLevel`.
130+ /// - Returns: Empty "to-do" context which should be eventually replaced with a carried through one, or `topLevel`.
131131 public static func TODO(
132132 _ reason: StaticString ? = " " ,
133133 function: String = #function,
134134 file: String = #file,
135135 line: UInt = #line
136136 ) -> ServiceContext {
137- var baggage = ServiceContext ( )
137+ var context = ServiceContext ( )
138138 #if BAGGAGE_CRASH_TODOS
139139 fatalError ( " BAGGAGE_CRASH_TODOS: at \( file) : \( line) (function \( function) ), reason: \( reason) " )
140+ #elseif SERVICE_CONTEXT_CRASH_TODOS
141+ fatalError ( " SERVICE_CONTEXT_CRASH_TODOS: at \( file) : \( line) (function \( function) ), reason: \( reason) " )
140142 #else
141- baggage [ TODOKey . self] = . init( file: file, line: line)
142- return baggage
143+ context [ TODOKey . self] = . init( file: file, line: line)
144+ return context
143145 #endif
144146 }
145147
@@ -151,8 +153,8 @@ extension ServiceContext {
151153 }
152154}
153155
154- /// Carried automatically by a "to do" baggage .
155- /// It can be used to track where a baggage originated and which "to do" baggage must be fixed into a real one to avoid this.
156+ /// Carried automatically by a "to do" context .
157+ /// It can be used to track where a context originated and which "to do" context must be fixed into a real one to avoid this.
156158public struct TODOLocation : Sendable {
157159 /// Source file location where the to-do ``ServiceContext`` was created
158160 public let file : String
@@ -163,7 +165,7 @@ public struct TODOLocation: Sendable {
163165// MARK: - Interacting with ServiceContext
164166
165167extension ServiceContext {
166- /// Provides type-safe access to the baggage 's values.
168+ /// Provides type-safe access to the context 's values.
167169 /// This API should ONLY be used inside of accessor implementations.
168170 ///
169171 /// End users should use "accessors" the key's author MUST define rather than using this subscript, following this pattern:
@@ -173,20 +175,20 @@ extension ServiceContext {
173175 /// }
174176 ///
175177 /// extension ServiceContext {
176- /// public internal(set) var testID: TestID? {
177- /// get {
178- /// self[TestIDKey.self]
178+ /// public internal(set) var testID: TestID? {
179+ /// get {
180+ /// self[TestIDKey.self]
181+ /// }
182+ /// set {
183+ /// self[TestIDKey.self] = newValue
184+ /// }
179185 /// }
180- /// set {
181- /// self[TestIDKey.self] = newValue
182- /// }
183- /// }
184186 /// }
185187 ///
186188 /// This is in order to enforce a consistent style across projects and also allow for fine grained control over
187189 /// who may set and who may get such property. Just access control to the Key type itself lacks such fidelity.
188190 ///
189- /// Note that specific baggage and context types MAY (and usually do), offer also a way to set baggage values,
191+ /// Note that specific context and context types MAY (and usually do), offer also a way to set context values,
190192 /// however in the most general case it is not required, as some frameworks may only be able to offer reading.
191193 public subscript< Key: ServiceContextKey > ( _ key: Key . Type ) -> Key . Value ? {
192194 get {
@@ -201,12 +203,12 @@ extension ServiceContext {
201203}
202204
203205extension ServiceContext {
204- /// The number of items in the baggage .
206+ /// The number of items in the context .
205207 public var count : Int {
206208 self . _storage. count
207209 }
208210
209- /// A Boolean value that indicates whether the baggage is empty.
211+ /// A Boolean value that indicates whether the context is empty.
210212 public var isEmpty : Bool {
211213 self . _storage. isEmpty
212214 }
0 commit comments