0
# scala3lib
1

2
scala3lib is a Scala 3 compatibility library for Scala Native that provides version-specific overrides and adaptations for native compilation. It serves as a bridge between the standard Scala 3 library and the Scala Native runtime, offering necessary modifications and optimizations for native compilation through patch files that override specific classes in the standard Scala 3 library.
3

4
## Package Information
5

6
- **Package Name**: scala3lib
7
- **Package Type**: Maven (org.scala-native:scala3lib_native0.5_3)
8
- **Language**: Scala
9
- **Version**: 0.5.8
10
- **Installation**: Include in your Scala Native project build configuration
11

12
## Core Imports
13

14
In a standard Scala Native project using Scala 3, scala3lib classes are automatically available as overrides to standard Scala 3 library classes:
15

16
```scala
17
import scala.runtime.LazyVals
18
import scala.reflect.Selectable
19
import scala.collection.immutable.List
20
import scala.collection.mutable.ArrayBuffer
21
import scala.concurrent.ExecutionContext
22
```
23

24
## Basic Usage
25

26
The library works transparently by providing Native-compatible implementations of standard Scala 3 classes. When you use standard Scala 3 APIs in a Scala Native project, the scala3lib overrides are automatically used:
27

28
```scala
29
// LazyVals automatically use Native-compatible implementation
30
object MyObject {
31
  lazy val expensiveValue: String = computeExpensiveString()
32
}
33

34
// Collection classes use optimized Native implementations  
35
val numbers = List(1, 2, 3, 4, 5)
36
val buffer = collection.mutable.ArrayBuffer[Int]()
37
buffer ++= numbers
38

39
// Reflection operations are handled safely
40
trait DynamicAccessor extends Selectable {
41
  // selectDynamic and applyDynamic are overridden to throw informative errors
42
}
43
```
44

45
## Architecture
46

47
scala3lib provides Native compatibility through several key mechanisms:
48

49
- **Version-Specific Overrides**: Patch files organized by Scala version (overrides-3, overrides-3.1, etc.) ensure compatibility across different Scala 3 releases
50
- **Runtime Adaptations**: Core runtime classes like LazyVals are adapted from JVM-specific implementations to Native-compatible versions
51
- **Reflection Limitations**: Reflection-based operations are replaced with clear error messages indicating Native limitations
52
- **Performance Optimizations**: Collection classes include @inline annotations and other optimizations for Native compilation
53
- **Cross-Compilation Support**: Depends on Scala 2.13 scalalib for compatibility during the compilation process
54

55
## Capabilities
56

57
### Runtime Operations
58

59
Core runtime functionality adapted for Scala Native, including lazy value initialization and thread-safe operations.
60

61
```scala { .api }
62
object LazyVals {
63
  // State management for lazy vals
64
  def STATE(cur: Long, ord: Int): Long
65
  
66
  // Multithreading-aware countdown latch
67
  class LazyCountDownLatch extends java.util.concurrent.CountDownLatch {
68
    def countDown(): Unit
69
    def await(): Unit
70
  }
71
  
72
  // Constants for lazy val state management
73
  val LAZY_VAL_MASK: Long
74
  val BITS_PER_LAZY_VAL: Int
75
  
76
  // JVM-specific operations that throw exceptions in Native context
77
  def CAS(t: Object, offset: Long, e: Long, v: Int, ord: Int): Boolean
78
  def objCAS(t: Object, offset: Long, exp: Object, n: Object): Boolean
79
  def setFlag(t: Object, offset: Long, v: Int, ord: Int): Unit
80
  def wait4Notification(t: Object, offset: Long, cur: Long, ord: Int): Unit
81
  def get(t: Object, off: Long): Long
82
  def getOffset(clz: Class[?], name: String): Long
83
  def getStaticFieldOffset(field: java.lang.reflect.Field): Long
84
  def getOffsetStatic(field: java.lang.reflect.Field): Long
85
}
86
```
87

88
### Reflection Operations
89

90
Dynamic selection and reflection operations with Native-specific limitations clearly indicated.
91

92
```scala { .api }
93
trait Selectable {
94
  // Dynamic member selection - throws exception in Native
95
  def selectDynamic(name: String): Any
96
  
97
  // Dynamic method invocation - throws exception in Native  
98
  def applyDynamic(name: String, paramTypes: Class[?]*)(args: Any*): Any
99
  
100
  // Protected method for accessing the selected value
101
  protected def selectedValue: Any
102
}
103
```
104

105
### Collection Operations
106

107
Optimized collection implementations for Native compilation, including both immutable and mutable collections.
108

109
```scala { .api }
110
// Immutable Collections
111
object List extends SeqFactory[List] {
112
  def newBuilder[A]: Builder[A, List[A]]
113
  def empty[A]: List[A] 
114
  def apply[A](xs: A*): List[A]
115
  def canBuildFrom[A]: CanBuildFrom[Coll, A, List[A]]
116
}
117

118
object Vector extends SeqFactory[Vector] {
119
  def newBuilder[A]: Builder[A, Vector[A]]
120
  def empty[A]: Vector[A]
121
  def apply[A](xs: A*): Vector[A]
122
}
123

124
object Set extends SetFactory[Set] {
125
  def newBuilder[A]: Builder[A, Set[A]]
126
  def empty[A]: Set[A]
127
  def apply[A](xs: A*): Set[A]
128
}
129

130
// Mutable Collections
131
class ArrayBuffer[A] extends mutable.Buffer[A] with mutable.IndexedSeq[A] {
132
  def +=(elem: A): this.type
133
  def insert(idx: Int, elem: A): Unit
134
  def remove(idx: Int): A
135
  def clear(): Unit
136
  def length: Int
137
  def apply(idx: Int): A
138
  def update(idx: Int, elem: A): Unit
139
}
140

141
class ListBuffer[A] extends mutable.Buffer[A] with mutable.LinearSeq[A] {
142
  def +=(elem: A): this.type
143
  def prepend(elem: A): this.type
144
  def insert(idx: Int, elem: A): Unit
145
  def remove(idx: Int): A
146
  def clear(): Unit
147
  def toList: List[A]
148
}
149
```
150

151
### Memory Management
152

153
Native-specific memory operations and atomic operations for thread-safe programming.
154

155
```scala { .api }
156
// VM utilities for memory operations (Scala 2.12 compatibility)
157
object VM {
158
  def releaseFence(): Unit
159
}
160
```
161

162
### Enumeration Support
163

164
Complete enumeration support ported from Scala.js for Native compatibility.
165

166
```scala { .api }
167
abstract class Enumeration(initial: Int) {
168
  def this() = this(0)
169
  
170
  protected var nextId: Int
171
  protected def nextName: String
172
  
173
  // Value creation methods
174
  protected def Value: Value
175
  protected def Value(name: String): Value  
176
  protected def Value(i: Int): Value
177
  protected def Value(i: Int, name: String): Value
178
  
179
  // Value access
180
  def values: ValueSet
181
  def apply(x: Int): Value
182
  def withName(s: String): Value
183
  
184
  // Value class
185
  abstract class Value extends Ordered[Value] with Serializable {
186
    def id: Int
187
    def toString: String
188
    def compare(that: Value): Int
189
  }
190
  
191
  // Value set operations
192
  class ValueSet extends mutable.Set[Value] with mutable.SortedSet[Value] {
193
    def iterator: Iterator[Value]
194
    def contains(v: Value): Boolean
195
    def +(v: Value): ValueSet
196
    def -(v: Value): ValueSet
197
  }
198
}
199
```
200

201
### Concurrent Programming
202

203
Execution context and concurrent data structures adapted for Native execution.
204

205
```scala { .api }
206
// Execution context for concurrent operations
207
trait ExecutionContext {
208
  def execute(runnable: Runnable): Unit
209
  def reportFailure(cause: Throwable): Unit
210
}
211

212
// Concurrent collections
213
class TrieMap[K, V] extends mutable.Map[K, V] with mutable.ConcurrentMap[K, V] {
214
  def get(key: K): Option[V]
215
  def put(key: K, value: V): Option[V]  
216
  def remove(key: K): Option[V]
217
  def putIfAbsent(key: K, value: V): Option[V]
218
  def replace(key: K, oldValue: V, newValue: V): Boolean
219
}
220
```
221

222
## Types
223

224
```scala { .api }
225
// Type class definitions for compilation
226
abstract class ClassTag[T] extends Equals with Serializable {
227
  def runtimeClass: Class[_]
228
}
229

230
abstract class Manifest[T] extends ClassTag[T] with Equals {
231
  def runtimeClass: Class[T]
232
  override def toString: String
233
}
234

235
// Builder pattern for collections
236
trait Builder[-Elem, +To] {
237
  def +=(elem: Elem): this.type
238
  def clear(): Unit
239
  def result(): To
240
}
241

242
// Factory pattern for collections  
243
trait GenericCanBuildFrom[-From, -Elem, +To] {
244
  def apply(): Builder[Elem, To]
245
}
246

247
// Validation and error handling
248
case class IllegalStateException(message: String) extends RuntimeException(message)
249
```
250

251
## Error Handling
252

253
scala3lib uses consistent error handling patterns to clearly indicate Native limitations:
254

255
- **Reflection Operations**: `selectDynamic` and `applyDynamic` throw `IllegalStateException` with message "Reflection is not fully supported in Scala Native"
256
- **LazyVals Operations**: JVM-specific unsafe operations throw `IllegalStateException` with message "Unexpected usage of scala.runtime.LazyVals method, in Scala Native lazy vals use overriden version of this class"
257
- **Thread Safety**: Operations are conditionally enabled based on `scala.scalanative.meta.LinktimeInfo.isMultithreadingEnabled`
258

259
## Dependencies
260

261
- **Scala 3 Library**: Base dependency on `scala3-library_3` for core Scala 3 functionality
262
- **Scala Native Runtime**: Uses `scala.scalanative.runtime` for Native-specific operations  
263
- **Scala Native Atomic Operations**: Uses `scala.scalanative.libc.stdatomic` for thread-safe memory operations
264
- **Cross-Compilation**: Depends on `org.scala-native:scalalib` (Scala 2.13 version) via `CrossVersion.for3Use2_13` for build compatibility
265

266
## Version Compatibility
267

268
The library provides version-specific overrides for multiple Scala 3 releases:
269

270
- **Scala 3.0**: Base overrides in `overrides-3/`
271
- **Scala 3.1**: Additional overrides in `overrides-3.1/`, `overrides-3.1.0/`, `overrides-3.1.1/`  
272
- **Scala 3.2**: Additional overrides in `overrides-3.2/`, `overrides-3.2.0/`, `overrides-3.2.1/`
273
- **Scala 3.3**: Additional overrides in `overrides-3.3/` through `overrides-3.3.4/`
274
- **Scala 3.4+**: Additional overrides in `overrides-3.4/`, `overrides-3.5/`, `overrides-3.5.2/`, `overrides-3.6/`
275

276
Each override directory contains patch files that modify specific classes for that Scala version, ensuring proper compilation and runtime behavior in the Scala Native environment.