0
# Native-Specific Overrides
1

2
Platform-specific implementations that replace or enhance standard Scala library components with native-optimized versions. These overrides provide better performance, memory management, and compatibility with the Scala Native runtime environment.
3

4
## Capabilities
5

6
### VM Memory Management
7

8
Native-optimized memory management utilities for collection operations, providing atomic memory fence operations using platform-specific implementations.
9

10
```scala { .api }
11
package scala.collection.immutable
12

13
/* private[immutable] */ object VM {
14
  /**
15
   * Performs a release memory fence operation using native atomic operations.
16
   * Ensures that all memory operations before this fence are visible to other threads
17
   * before any memory operations after the fence.
18
   * 
19
   * Used internally by immutable collections for thread-safe operations.
20
   * Implementation: atomic_thread_fence(memory_order_release)
21
   */
22
  def releaseFence(): Unit
23
}
24
```
25

26
**Usage Example:**
27

28
```scala
29
import scala.collection.immutable.VM
30

31
// Used internally by collections, but can be called directly for custom thread-safe operations
32
class ThreadSafeCounter {
33
  @volatile private var count = 0
34
  
35
  def increment(): Unit = {
36
    count += 1
37
    VM.releaseFence() // Ensure visibility to other threads
38
  }
39
  
40
  def get(): Int = count
41
}
42
```
43

44
### Enhanced Enumeration Implementation
45

46
Native-specific implementation of Scala enumerations with improved performance and Scala.js compatibility. Provides the complete enumeration API with native-optimized value storage and retrieval.
47

48
```scala { .api }
49
abstract class Enumeration(initial: Int) extends Serializable {
50
  /**
51
   * Creates an enumeration starting from id 0.
52
   */
53
  def this(): Enumeration
54
  
55
  /**
56
   * The values of this enumeration as a set.
57
   * @return ValueSet containing all defined enumeration values
58
   */
59
  def values: ValueSet
60
  
61
  /**
62
   * Returns the enumeration value with the given id.
63
   * @param x the id of the value
64
   * @return the enumeration value
65
   * @throws NoSuchElementException if no value with given id exists
66
   */
67
  def apply(x: Int): Value
68
  
69
  /**
70
   * Returns the enumeration value with the given name.
71
   * @param s the name of the value
72
   * @return the enumeration value
73
   * @throws NoSuchElementException if no value with given name exists
74
   */
75
  def withName(s: String): Value
76
  
77
  /**
78
   * The highest integer amongst those used to identify values in this enumeration.
79
   * @return the maximum id used
80
   */
81
  def maxId: Int
82
  
83
  /**
84
   * Returns the string representation of this enumeration (the class name).
85
   * @return the class name without package and $ suffix
86
   */
87
  override def toString: String
88
  
89
  /**
90
   * Creates a fresh value, part of this enumeration, with auto-generated id.
91
   * @return new enumeration value
92
   */
93
  protected def Value: Value
94
  
95
  /**
96
   * Creates a fresh value with specified id.
97
   * @param i unique identifier for this value
98
   * @return new enumeration value
99
   */
100
  protected def Value(i: Int): Value
101
  
102
  /**
103
   * Creates a fresh value with specified name.
104
   * @param name human-readable name for this value
105
   * @return new enumeration value
106
   */
107
  protected def Value(name: String): Value
108
  
109
  /**
110
   * Creates a fresh value with specified id and name.
111
   * @param i unique identifier for this value
112
   * @param name human-readable name for this value
113
   * @return new enumeration value
114
   */
115
  protected def Value(i: Int, name: String): Value
116
}
117
```
118

119
### Enumeration Value Type
120

121
```scala { .api }
122
abstract class Enumeration#Value extends Ordered[Value] with Serializable {
123
  /**
124
   * The unique identifier of this enumeration value.
125
   * @return the id as an integer
126
   */
127
  def id: Int
128
  
129
  /**
130
   * Compares this value with another enumeration value.
131
   * @param that the value to compare with
132
   * @return negative, zero, or positive integer as this value is less than, equal to, or greater than that
133
   */
134
  def compare(that: Value): Int
135
  
136
  /**
137
   * Creates a ValueSet containing this value and another value.
138
   * @param v the other value to include
139
   * @return ValueSet containing both values
140
   */
141
  def +(v: Value): ValueSet
142
}
143
```
144

145
### Enumeration ValueSet
146

147
```scala { .api }
148
class Enumeration#ValueSet extends immutable.SortedSet[Value] with Serializable {
149
  /**
150
   * Tests whether this set contains the given value.
151
   * @param v the value to test
152
   * @return true if the value is in this set
153
   */
154
  def contains(v: Value): Boolean
155
  
156
  /**
157
   * Creates a new set with an additional value.
158
   * @param value the value to add
159
   * @return new ValueSet containing the additional value
160
   */
161
  def +(value: Value): ValueSet
162
  
163
  /**
164
   * Creates a new set with a value removed.
165
   * @param value the value to remove
166
   * @return new ValueSet without the specified value
167
   */
168
  def -(value: Value): ValueSet
169
  
170
  /**
171
   * Creates an iterator over the values in this set in increasing order of their ids.
172
   * @return iterator over the enumeration values
173
   */
174
  def iterator: Iterator[Value]
175
  
176
  /**
177
   * Creates a bit mask for the zero-adjusted ids in this set.
178
   * @return array of longs representing the bit mask
179
   */
180
  def toBitMask: Array[Long]
181
}
182
```
183

184
### ValueSet Factory
185

186
```scala { .api }
187
object Enumeration#ValueSet {
188
  /**
189
   * The empty value set.
190
   */
191
  val empty: ValueSet
192
  
193
  /**
194
   * Creates a value set consisting of given elements.
195
   * @param elems the values to include
196
   * @return ValueSet containing the specified values
197
   */
198
  def apply(elems: Value*): ValueSet
199
  
200
  /**
201
   * Creates a value set from a bit mask representation.
202
   * @param elems array of longs representing the bit mask
203
   * @return ValueSet corresponding to the bit mask
204
   */
205
  def fromBitMask(elems: Array[Long]): ValueSet
206
  
207
  /**
208
   * Creates a builder for constructing ValueSets.
209
   * @return mutable builder for ValueSet
210
   */
211
  def newBuilder: mutable.Builder[Value, ValueSet]
212
}
213
```
214

215
### Enumeration Val Implementation
216

217
```scala { .api }
218
protected class Enumeration#Val(i: Int, name: String) extends Value with Serializable {
219
  /**
220
   * Creates a Val with specified id and auto-generated name.
221
   * @param i the unique identifier
222
   */
223
  def this(i: Int): Val
224
  
225
  /**
226
   * Creates a Val with auto-generated id and specified name.
227
   * @param name the human-readable name
228
   */
229
  def this(name: String): Val
230
  
231
  /**
232
   * Creates a Val with auto-generated id and name.
233
   */
234
  def this(): Val
235
  
236
  /**
237
   * The unique identifier of this value.
238
   * @return the id as an integer
239
   */
240
  def id: Int
241
  
242
  /**
243
   * String representation of this value (name or placeholder).
244
   * @return the name if provided, otherwise a placeholder with id and class
245
   */
246
  override def toString(): String
247
}
248
```
249

250
### Value Ordering
251

252
```scala { .api }
253
object Enumeration#ValueOrdering extends Ordering[Value] {
254
  /**
255
   * Compares two enumeration values by their ids.
256
   * @param x first value
257
   * @param y second value
258
   * @return negative, zero, or positive integer comparison result
259
   */
260
  def compare(x: Value, y: Value): Int
261
}
262
```
263

264
**Usage Example:**
265

266
```scala
267
object Color extends Enumeration {
268
  type Color = Value
269
  val Red, Green, Blue, Yellow, Orange = Value
270
}
271

272
object Priority extends Enumeration {
273
  val Low = Value(1, "low")
274
  val Medium = Value(5, "medium") 
275
  val High = Value(10, "high")
276
}
277

278
// Usage
279
val color = Color.Red
280
val priority = Priority.withName("high")
281

282
// Create sets of values
283
val primaryColors = Color.ValueSet(Color.Red, Color.Green, Color.Blue)
284
val importantPriorities = Priority.High + Priority.Medium
285

286
// Iterate over all values
287
for (c <- Color.values) {
288
  println(s"Color: $c (id: ${c.id})")
289
}
290
```
291

292
## Implementation Notes
293

294
- **Thread Safety**: All override implementations are designed to be thread-safe in the native runtime environment
295
- **Memory Efficiency**: Native-specific memory management reduces overhead compared to JVM implementations
296
- **Compatibility**: Maintains full API compatibility with standard Scala library while providing native optimizations
297
- **Version Support**: Overrides are provided for multiple Scala versions (2.12, 2.13, 3.x) with version-specific optimizations