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
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.scala-native/nativelib_native0.5_3@0.5.x
Publish Source
CLI
Badge
tessl/maven-org-scala-native--nativelib-native0-5-3 badge