CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Pending
Overview
Eval results
Files

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.

Install with Tessl CLI

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