0
# Attributes & Type System
1

2
Type-safe attribute storage system for associating typed values with keys across different application contexts. The attributes system provides a way to store and retrieve typed values using keys, ensuring type safety at compile time.
3

4
## Capabilities
5

6
### AttributeKey Creation
7

8
Creates a typed key for storing values in an attributes map.
9

10
```kotlin { .api }
11
/**
12
 * Creates an attribute key with the specified name and inferred type
13
 * @param name Name of the attribute for diagnostic purposes
14
 * @return AttributeKey instance for the specified type
15
 */
16
inline fun <reified T : Any> AttributeKey(name: String): AttributeKey<T>
17

18
/**
19
 * Creates an attribute key with explicit type information
20
 * @param name Name of the attribute
21
 * @param type Type information for the attribute value
22
 */
23
data class AttributeKey<T : Any>(
24
    val name: String,
25
    private val type: TypeInfo = typeInfo<Any>()
26
)
27
```
28

29
**Usage Examples:**
30

31
```kotlin
32
import io.ktor.util.*
33

34
// Create typed attribute keys
35
val userIdKey = AttributeKey<Int>("userId")
36
val sessionKey = AttributeKey<String>("sessionId")
37
val configKey = AttributeKey<Map<String, Any>>("config")
38

39
// Keys can be reused across different attribute instances
40
val attributes1 = Attributes()
41
val attributes2 = Attributes()
42
attributes1.put(userIdKey, 123)
43
attributes2.put(userIdKey, 456)
44
```
45

46
### Attributes Interface
47

48
Main interface for type-safe attribute storage and retrieval.
49

50
```kotlin { .api }
51
/**
52
 * Map of attributes accessible by AttributeKey in a typed manner
53
 */
54
interface Attributes {
55
    /** Gets a value or throws exception if not found */
56
    operator fun <T : Any> get(key: AttributeKey<T>): T
57
    
58
    /** Gets a value or returns null if not found */
59
    fun <T : Any> getOrNull(key: AttributeKey<T>): T?
60
    
61
    /** Checks if an attribute exists */
62
    operator fun contains(key: AttributeKey<*>): Boolean
63
    
64
    /** Creates or changes an attribute value */
65
    fun <T : Any> put(key: AttributeKey<T>, value: T)
66
    
67
    /** Creates or changes an attribute value (operator form) */
68
    operator fun <T : Any> set(key: AttributeKey<T>, value: T)
69
    
70
    /** Removes an attribute */
71
    fun <T : Any> remove(key: AttributeKey<T>)
72
    
73
    /** Removes and returns an attribute value, throws if not found */
74
    fun <T : Any> take(key: AttributeKey<T>): T
75
    
76
    /** Removes and returns an attribute value, returns null if not found */
77
    fun <T : Any> takeOrNull(key: AttributeKey<T>): T?
78
    
79
    /** Gets or computes a value if absent */
80
    fun <T : Any> computeIfAbsent(key: AttributeKey<T>, block: () -> T): T
81
    
82
    /** Returns list of all attribute keys */
83
    val allKeys: List<AttributeKey<*>>
84
}
85
```
86

87
**Usage Examples:**
88

89
```kotlin
90
import io.ktor.util.*
91

92
val attributes = Attributes()
93
val nameKey = AttributeKey<String>("name")
94
val ageKey = AttributeKey<Int>("age")
95

96
// Store values
97
attributes.put(nameKey, "Alice")
98
attributes[ageKey] = 30
99

100
// Retrieve values
101
val name = attributes[nameKey] // Returns "Alice"
102
val age = attributes.getOrNull(ageKey) // Returns 30 or null
103

104
// Check existence
105
if (nameKey in attributes) {
106
    println("Name is present")
107
}
108

109
// Compute if absent
110
val defaultAge = attributes.computeIfAbsent(ageKey) { 25 }
111

112
// Remove values
113
val removedName = attributes.take(nameKey) // Returns and removes
114
attributes.remove(ageKey) // Just removes
115
```
116

117
### Attributes Factory
118

119
Creates platform-appropriate attributes instances.
120

121
```kotlin { .api }
122
/**
123
 * Creates an attributes instance suitable for the particular platform
124
 * @param concurrent Whether the attributes should be thread-safe
125
 * @return Platform-specific Attributes implementation
126
 */
127
fun Attributes(concurrent: Boolean = false): Attributes
128
```
129

130
**Usage Examples:**
131

132
```kotlin
133
import io.ktor.util.*
134

135
// Create standard attributes
136
val attrs = Attributes()
137

138
// Create thread-safe attributes for concurrent access
139
val concurrentAttrs = Attributes(concurrent = true)
140

141
// Use across multiple threads safely
142
val userKey = AttributeKey<String>("user")
143
concurrentAttrs.put(userKey, "Alice")
144
```
145

146
### Utility Functions
147

148
Additional utility functions for working with attributes.
149

150
```kotlin { .api }
151
/**
152
 * Adds all attributes from another collection, replacing original values if any
153
 * @param other Source attributes to copy from
154
 */
155
fun Attributes.putAll(other: Attributes)
156
```
157

158
**Usage Examples:**
159

160
```kotlin
161
import io.ktor.util.*
162

163
val source = Attributes()
164
val target = Attributes()
165

166
val nameKey = AttributeKey<String>("name")
167
val ageKey = AttributeKey<Int>("age")
168

169
source.put(nameKey, "Bob")
170
source.put(ageKey, 25)
171

172
// Copy all attributes from source to target
173
target.putAll(source)
174

175
println(target[nameKey]) // "Bob"
176
println(target[ageKey])  // 25
177
```
178

179
## Type Information System
180

181
The type system provides runtime type information for generic operations.
182

183
### TypeInfo
184

185
Represents type information for runtime type operations.
186

187
```kotlin { .api }
188
/**
189
 * Provides type information for the specified generic type
190
 * @return TypeInfo instance representing the type T
191
 */
192
inline fun <reified T> typeInfo(): TypeInfo
193

194
/**
195
 * Type information holder for runtime type operations
196
 */
197
class TypeInfo
198
```
199

200
**Usage Examples:**
201

202
```kotlin
203
import io.ktor.util.reflect.*
204

205
// Get type information for different types
206
val stringType = typeInfo<String>()
207
val listType = typeInfo<List<String>>()
208
val mapType = typeInfo<Map<String, Int>>()
209

210
// Use with attribute keys for explicit typing
211
val explicitKey = AttributeKey<List<String>>("items", typeInfo<List<String>>())
212
```