0
# Scala Native Auxlib
1

2
The auxlib library provides essential runtime support components for Scala Native, including boxed primitive types, concurrent collection infrastructure, array utilities, reference type wrappers, and mathematical abstractions. This low-level library serves as a foundational layer for Scala Native's runtime system, enabling proper interoperability between Scala's type system and native code execution.
3

4
## Package Information
5

6
- **Package Name**: org.scala-native:auxlib_native0.5_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to build.sbt: `libraryDependencies += "org.scala-native" %%% "auxlib" % "0.5.7"`
10

11
## Core Imports
12

13
```scala
14
import scala.runtime.BoxesRunTime
15
import scala.runtime.{BooleanRef, IntRef, ObjectRef}
16
import scala.math.ScalaNumber
17
import scala.collection.concurrent.{BasicNode, MainNode}
18
```
19

20
## Basic Usage
21

22
```scala
23
import scala.runtime.BoxesRunTime
24
import scala.runtime.IntRef
25

26
// Boxing and unboxing primitives
27
val boxedInt = BoxesRunTime.boxToInteger(42)
28
val unboxedInt = BoxesRunTime.unboxToInt(boxedInt)
29

30
// Using reference types for mutable variables
31
val intRef = IntRef.create(10)
32
intRef.elem = 20
33
println(intRef.elem) // 20
34

35
// Arithmetic operations on boxed values
36
val a = BoxesRunTime.boxToInteger(5)
37
val b = BoxesRunTime.boxToInteger(3)
38
val sum = BoxesRunTime.add(a, b)
39
val result = BoxesRunTime.unboxToInt(sum) // 8
40
```
41

42
## Architecture
43

44
The auxlib library is organized into five main functional areas:
45

46
- **Boxing/Unboxing System**: Complete primitive type boxing with comprehensive operators for arithmetic, bitwise, and logical operations
47
- **Reference Types**: Mutable and volatile reference wrappers for all primitive and object types
48
- **Array Utilities**: Array cloning support for all primitive array types
49
- **Concurrent Collection Infrastructure**: Base classes and atomic field updaters for lock-free concurrent data structures
50
- **Mathematical Abstractions**: Base classes for Scala's numeric type hierarchy
51

52
This design provides the essential runtime infrastructure that bridges Scala language features with native compilation and execution models.
53

54
## Capabilities
55

56
### Boxing and Unboxing Operations
57

58
Comprehensive boxing/unboxing utilities with arithmetic, bitwise, and logical operators for primitive types. Handles type coercion and provides runtime support for Scala's unified type system.
59

60
```scala { .api }
61
object BoxesRunTime {
62
  def boxToInteger(v: Int): java.lang.Integer
63
  def unboxToInt(o: java.lang.Object): Int
64
  def add(arg1: java.lang.Object, arg2: java.lang.Object): java.lang.Object
65
  def equals(x: java.lang.Object, y: java.lang.Object): Boolean
66
}
67
```
68

69
[Boxing and Unboxing](./boxing-unboxing.md)
70

71
### Reference Type Wrappers
72

73
Mutable and volatile reference wrappers for all primitive types and objects. Provides thread-safe access patterns and atomic operations support.
74

75
```scala { .api }
76
class IntRef(var elem: Int) extends Serializable
77
object IntRef {
78
  def create(elem: Int): IntRef
79
  def zero(): IntRef
80
}
81

82
class VolatileIntRef(@volatile var elem: Int) extends Serializable
83
```
84

85
[Reference Types](./reference-types.md)
86

87
### Array Runtime Support
88

89
Array cloning utilities supporting all primitive array types and object arrays with proper type preservation.
90

91
```scala { .api }
92
object ArrayRuntime {
93
  def cloneArray(array: Array[Int]): Array[Int]
94
  def cloneArray(array: Array[java.lang.Object]): Array[java.lang.Object]
95
}
96
```
97

98
[Array Runtime](./array-runtime.md)
99

100
### Concurrent Collection Infrastructure
101

102
Base classes and atomic field updaters for building lock-free concurrent data structures. Provides the foundation for Scala's concurrent collections.
103

104
```scala { .api }
105
abstract class BasicNode {
106
  def string(lev: Int): String
107
}
108

109
abstract class MainNode[K <: AnyRef, V <: AnyRef] extends BasicNode {
110
  def cachedSize(ct: Object): Int
111
  def knownSize(): Int
112
}
113
```
114

115
[Concurrent Collections](./concurrent-collections.md)
116

117
### Mathematical Number Support
118

119
Abstract base classes for Scala's numeric type hierarchy, providing foundation for custom numeric types and mathematical operations.
120

121
```scala { .api }
122
abstract class ScalaNumber extends java.lang.Number {
123
  protected def isWhole(): Boolean
124
  def underlying(): Object
125
}
126
```
127

128
[Mathematical Support](./mathematical-support.md)
129

130
## Types
131

132
### Common Reference Types
133

134
```scala { .api }
135
class BooleanRef(var elem: Boolean) extends Serializable
136
class CharRef(var elem: Char) extends Serializable  
137
class ByteRef(var elem: Byte) extends Serializable
138
class ShortRef(var elem: Short) extends Serializable
139
class IntRef(var elem: Int) extends Serializable
140
class LongRef(var elem: Long) extends Serializable
141
class FloatRef(var elem: Float) extends Serializable
142
class DoubleRef(var elem: Double) extends Serializable
143
class ObjectRef[A](var elem: A) extends Serializable
144
```
145

146
### Volatile Reference Types
147

148
```scala { .api }
149
class VolatileBooleanRef(@volatile var elem: Boolean) extends Serializable
150
class VolatileIntRef(@volatile var elem: Int) extends Serializable
151
class VolatileObjectRef[A](@volatile var elem: A) extends Serializable
152
```
153

154
### Concurrent Collection Base Types
155

156
```scala { .api }
157
abstract class BasicNode
158
abstract class MainNode[K <: AnyRef, V <: AnyRef] extends BasicNode
159
abstract class INodeBase[K <: AnyRef, V <: AnyRef](generation: Gen) extends BasicNode
160
abstract class CNodeBase[K <: AnyRef, V <: AnyRef] extends MainNode[K, V]
161
```