or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-scala-native--scala3lib-native0-5-3

Scala 3 compatibility library for Scala Native providing version-specific overrides and adaptations for native compilation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.scala-native/scala3lib_native0.5_3@0.5.x

To install, run

npx @tessl/cli install tessl/maven-org-scala-native--scala3lib-native0-5-3@0.5.0

index.mddocs/

scala3lib

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.

Package Information

  • Package Name: scala3lib
  • Package Type: Maven (org.scala-native:scala3lib_native0.5_3)
  • Language: Scala
  • Version: 0.5.8
  • Installation: Include in your Scala Native project build configuration

Core Imports

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

import scala.runtime.LazyVals
import scala.reflect.Selectable
import scala.collection.immutable.List
import scala.collection.mutable.ArrayBuffer
import scala.concurrent.ExecutionContext

Basic Usage

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:

// LazyVals automatically use Native-compatible implementation
object MyObject {
  lazy val expensiveValue: String = computeExpensiveString()
}

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

// Reflection operations are handled safely
trait DynamicAccessor extends Selectable {
  // selectDynamic and applyDynamic are overridden to throw informative errors
}

Architecture

scala3lib provides Native compatibility through several key mechanisms:

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

Capabilities

Runtime Operations

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

object LazyVals {
  // State management for lazy vals
  def STATE(cur: Long, ord: Int): Long
  
  // Multithreading-aware countdown latch
  class LazyCountDownLatch extends java.util.concurrent.CountDownLatch {
    def countDown(): Unit
    def await(): Unit
  }
  
  // Constants for lazy val state management
  val LAZY_VAL_MASK: Long
  val BITS_PER_LAZY_VAL: Int
  
  // JVM-specific operations that throw exceptions in Native context
  def CAS(t: Object, offset: Long, e: Long, v: Int, ord: Int): Boolean
  def objCAS(t: Object, offset: Long, exp: Object, n: Object): Boolean
  def setFlag(t: Object, offset: Long, v: Int, ord: Int): Unit
  def wait4Notification(t: Object, offset: Long, cur: Long, ord: Int): Unit
  def get(t: Object, off: Long): Long
  def getOffset(clz: Class[?], name: String): Long
  def getStaticFieldOffset(field: java.lang.reflect.Field): Long
  def getOffsetStatic(field: java.lang.reflect.Field): Long
}

Reflection Operations

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

trait Selectable {
  // Dynamic member selection - throws exception in Native
  def selectDynamic(name: String): Any
  
  // Dynamic method invocation - throws exception in Native  
  def applyDynamic(name: String, paramTypes: Class[?]*)(args: Any*): Any
  
  // Protected method for accessing the selected value
  protected def selectedValue: Any
}

Collection Operations

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

// Immutable Collections
object List extends SeqFactory[List] {
  def newBuilder[A]: Builder[A, List[A]]
  def empty[A]: List[A] 
  def apply[A](xs: A*): List[A]
  def canBuildFrom[A]: CanBuildFrom[Coll, A, List[A]]
}

object Vector extends SeqFactory[Vector] {
  def newBuilder[A]: Builder[A, Vector[A]]
  def empty[A]: Vector[A]
  def apply[A](xs: A*): Vector[A]
}

object Set extends SetFactory[Set] {
  def newBuilder[A]: Builder[A, Set[A]]
  def empty[A]: Set[A]
  def apply[A](xs: A*): Set[A]
}

// Mutable Collections
class ArrayBuffer[A] extends mutable.Buffer[A] with mutable.IndexedSeq[A] {
  def +=(elem: A): this.type
  def insert(idx: Int, elem: A): Unit
  def remove(idx: Int): A
  def clear(): Unit
  def length: Int
  def apply(idx: Int): A
  def update(idx: Int, elem: A): Unit
}

class ListBuffer[A] extends mutable.Buffer[A] with mutable.LinearSeq[A] {
  def +=(elem: A): this.type
  def prepend(elem: A): this.type
  def insert(idx: Int, elem: A): Unit
  def remove(idx: Int): A
  def clear(): Unit
  def toList: List[A]
}

Memory Management

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

// VM utilities for memory operations (Scala 2.12 compatibility)
object VM {
  def releaseFence(): Unit
}

Enumeration Support

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

abstract class Enumeration(initial: Int) {
  def this() = this(0)
  
  protected var nextId: Int
  protected def nextName: String
  
  // Value creation methods
  protected def Value: Value
  protected def Value(name: String): Value  
  protected def Value(i: Int): Value
  protected def Value(i: Int, name: String): Value
  
  // Value access
  def values: ValueSet
  def apply(x: Int): Value
  def withName(s: String): Value
  
  // Value class
  abstract class Value extends Ordered[Value] with Serializable {
    def id: Int
    def toString: String
    def compare(that: Value): Int
  }
  
  // Value set operations
  class ValueSet extends mutable.Set[Value] with mutable.SortedSet[Value] {
    def iterator: Iterator[Value]
    def contains(v: Value): Boolean
    def +(v: Value): ValueSet
    def -(v: Value): ValueSet
  }
}

Concurrent Programming

Execution context and concurrent data structures adapted for Native execution.

// Execution context for concurrent operations
trait ExecutionContext {
  def execute(runnable: Runnable): Unit
  def reportFailure(cause: Throwable): Unit
}

// Concurrent collections
class TrieMap[K, V] extends mutable.Map[K, V] with mutable.ConcurrentMap[K, V] {
  def get(key: K): Option[V]
  def put(key: K, value: V): Option[V]  
  def remove(key: K): Option[V]
  def putIfAbsent(key: K, value: V): Option[V]
  def replace(key: K, oldValue: V, newValue: V): Boolean
}

Types

// Type class definitions for compilation
abstract class ClassTag[T] extends Equals with Serializable {
  def runtimeClass: Class[_]
}

abstract class Manifest[T] extends ClassTag[T] with Equals {
  def runtimeClass: Class[T]
  override def toString: String
}

// Builder pattern for collections
trait Builder[-Elem, +To] {
  def +=(elem: Elem): this.type
  def clear(): Unit
  def result(): To
}

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

// Validation and error handling
case class IllegalStateException(message: String) extends RuntimeException(message)

Error Handling

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

  • Reflection Operations: selectDynamic and applyDynamic throw IllegalStateException with message "Reflection is not fully supported in Scala Native"
  • 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"
  • Thread Safety: Operations are conditionally enabled based on scala.scalanative.meta.LinktimeInfo.isMultithreadingEnabled

Dependencies

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

Version Compatibility

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

  • Scala 3.0: Base overrides in overrides-3/
  • Scala 3.1: Additional overrides in overrides-3.1/, overrides-3.1.0/, overrides-3.1.1/
  • Scala 3.2: Additional overrides in overrides-3.2/, overrides-3.2.0/, overrides-3.2.1/
  • Scala 3.3: Additional overrides in overrides-3.3/ through overrides-3.3.4/
  • Scala 3.4+: Additional overrides in overrides-3.4/, overrides-3.5/, overrides-3.5.2/, overrides-3.6/

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.