CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Native interoperability library for Scala Native providing unsafe operations, C-style data types, and memory management primitives for direct interaction with native code

—

Pending
Overview
Eval results
Files

Scala Native nativelib

Scala Native nativelib is the core native interoperability library for Scala Native, providing comprehensive facilities for unsafe operations, memory management, and C-style data types. It enables Scala programs compiled to native code to interface directly with C/C++ libraries, system calls, and low-level memory operations while maintaining type safety where possible.

Package Information

  • Package Name: org.scala-native:nativelib_native0.5_3
  • Package Type: maven
  • Language: Scala
  • Installation: Add to build.sbt: libraryDependencies += "org.scala-native" %%% "nativelib" % "0.5.7"

Core Imports

import scala.scalanative.unsafe._
import scala.scalanative.unsigned._
import scala.scalanative.runtime._

Individual package imports:

import scala.scalanative.unsafe.{Zone, Ptr, CString, CInt}
import scala.scalanative.unsigned.{UInt, ULong}
import scala.scalanative.runtime.{Array => NativeArray}

Basic Usage

import scala.scalanative.unsafe._
import scala.scalanative.unsigned._

// Memory allocation with automatic cleanup
Zone.acquire { implicit z =>
  // Allocate a C string
  val cstr: CString = toCString("Hello, Native World!")
  
  // Convert back to Scala string
  val scalaStr: String = fromCString(cstr)
  
  // Allocate typed memory
  val intPtr: Ptr[CInt] = alloc[CInt](10) // allocate 10 integers
  intPtr(0) = 42  // set first element
  val value: CInt = intPtr(0)  // read first element
  
  // Work with unsigned integers
  val unsigned: UInt = 42.toUInt
  val result: UInt = unsigned + 10.toUInt
}

Architecture

Scala Native nativelib is organized around several core concepts:

  • Memory Management: Zone-based allocation provides automatic memory cleanup and leak prevention
  • Type Safety: Strong typing through Ptr[T], Tag[T], and sized types while allowing unsafe operations when needed
  • C Interoperability: Direct mapping between Scala and C types with zero-cost abstractions
  • Unsigned Arithmetic: Full unsigned integer support with proper overflow semantics
  • Native Arrays: High-performance array types optimized for native code generation
  • Function Pointers: Type-safe function pointer interface for callbacks and native function calls

Capabilities

Memory Management and Pointers

Core pointer operations, memory allocation, zone-based memory management, type-safe memory operations with the Tag system, and low-level runtime intrinsics for performance-critical code.

trait Zone {
  def alloc(size: CSize): Ptr[Byte]
  def close(): Unit
  def isClosed: Boolean
}

object Zone {
  def acquire[T](f: Zone => T): T
  def open(): Zone
}

final class Ptr[T] {
  def unary_!(implicit tag: Tag[T]): T
  def unary_!_=(value: T)(implicit tag: Tag[T]): Unit
  def +(offset: Int)(implicit tag: Tag[T]): Ptr[T]
  def -(offset: Int)(implicit tag: Tag[T]): Ptr[T]
  def apply(offset: Int)(implicit tag: Tag[T]): T
  def update(offset: Int, value: T)(implicit tag: Tag[T]): Unit
}

Memory Management

C Data Types and Interoperability

Comprehensive C type system including primitive types, strings, arrays, complete CStruct0-22 structure families, complete CFuncPtr0-22 function pointer families, and variadic arguments for seamless C library integration.

// C type aliases
type CInt = Int
type CString = Ptr[CChar]
type CChar = Byte
type CSize = USize

// String conversions
def fromCString(cstr: CString, charset: Charset = Charset.defaultCharset()): String
def toCString(str: String)(implicit z: Zone): CString
def toCString(str: String, charset: Charset)(implicit z: Zone): CString

// C arrays and structures
final class CArray[T, N <: Nat] {
  def length(implicit tag: Tag[N]): Int
  def apply(idx: Int)(implicit tag: Tag[T]): T
  def update(idx: Int, value: T)(implicit tag: Tag[T]): Unit
  def at(idx: Int)(implicit tag: Tag[T]): Ptr[T]
}

// Function pointers (0-22 arity)
abstract class CFuncPtr0[R] {
  def apply(): R
}
abstract class CFuncPtr1[T1, R] {
  def apply(arg1: T1): R
}

C Interoperability

Unsigned Integer Types

Full-featured unsigned integer arithmetic with proper overflow semantics and conversions for systems programming.

final class UByte extends AnyVal {
  def +(other: UByte): UByte
  def -(other: UByte): UByte
  def *(other: UByte): UByte
  def /(other: UByte): UByte
  def %(other: UByte): UByte
  def &(other: UByte): UByte
  def |(other: UByte): UByte
  def ^(other: UByte): UByte
  def <<(shift: Int): UByte
  def >>(shift: Int): UByte
  def >>>(shift: Int): UByte
}

// Similar interfaces for UShort, UInt, ULong, USize

Unsigned Types

Native Arrays and Runtime

High-performance native array types and comprehensive runtime utilities including complete garbage collector interface, thread management, root set management, runtime information, and system integration.

sealed abstract class Array[T] {
  def length: Int
  def stride: Int
  def at(i: Int): Ptr[T]
  def apply(i: Int): T
  def update(i: Int, value: T): Unit
  def clone(): Array[T]
}

// Typed array implementations
final class IntArray extends Array[Int]
final class FloatArray extends Array[Float]
final class ObjectArray[T] extends Array[T]

// GC interface
object GC {
  def getInitHeapSize(): ULong
  def getMaxHeapSize(): ULong  
  def getUsedHeapSize(): ULong
  def collect(): Unit
}

Native Arrays and Runtime

Annotations and Compiler Directives

Comprehensive annotation system including optimization control, memory layout, external interface declarations, memory model consistency, reflection support, and development utilities for fine-tuning native code generation and interoperability.

class alwaysinline extends scala.annotation.StaticAnnotation
class noinline extends scala.annotation.StaticAnnotation
class nooptimize extends scala.annotation.StaticAnnotation
class align(size: Int, group: String = "") extends scala.annotation.StaticAnnotation
class extern extends scala.annotation.StaticAnnotation
class blocking extends scala.annotation.StaticAnnotation

Annotations

Types

// Platform-dependent size types
type Size = /* Int on 32-bit, Long on 64-bit */
type USize = /* UInt on 32-bit, ULong on 64-bit */

// Tag system for type information
trait Tag[T] {
  def size: Size
  def load(ptr: Ptr[Byte]): T
  def store(ptr: Ptr[Byte], value: T): Unit
}

// Natural numbers for array sizes
sealed abstract class Nat
object Nat {
  class _0 extends Nat
  class _1 extends Nat
  class _2 extends Nat
  // ... continues to higher numbers
}

Safety and Best Practices

  • Always use Zone.acquire: Automatic memory management prevents leaks
  • Null checks: C interop may introduce null pointers - check before dereferencing
  • Charset handling: Specify charsets explicitly when converting strings
  • Type tags: Required for generic operations - usually inferred automatically
  • Unsigned arithmetic: Be aware of overflow behavior in unsigned operations
  • External annotations: Use @extern and @blocking appropriately for native functions

Install with Tessl CLI

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