feat: minimal stub implementation for kyo-offheap

[akhilender-bongirwar]

Adds a minimal stub implementation for kyo-offheap to enable support for Scala Native.

• Arena class manages off-heap memory allocations with automatic deallocation.
• MemorySegment class provides basic operations for slicing and accessing primitive values in off-heap memory.

This implementation forms the basis for integrating off-heap memory management with Scala Native in the kyo-offheap module.

Related Issue - #1053

/claim #1053

[sideeffffect]

Nice! I have a few suggestions for improvement.

[HollandDM]

From my past attempt for this problem, the biggest challenge was how to create a native Arena.ofShared correctly according to JDK requirements, especially the requirements of thread-safe close an Arena. This stub can lead to a scenario when multi threads try to free the same allocation, which is an undefined behavior.

[sideeffffect]

Thanks for implementing my suggestions. There is still some work that needs to be done.

[sideeffffect]

We're getting there.

[fwbrasil]

Thank you for the contribution! This is looking promising :) I took a look at the build and the new native implementation isn't being tested, we also need changes in the SBT build:

diff --git a/build.sbt b/build.sbt
index 2de5dd29..5fa03824 100644
--- a/build.sbt
+++ b/build.sbt
@@ -161,6 +161,7 @@ lazy val kyoNative = project
         `kyo-stats-registry`.native,
         `kyo-scheduler`.native,
         `kyo-core`.native,
+        `kyo-offheap`.native,
         `kyo-direct`.native,
         `kyo-combinators`.native,
         `kyo-sttp`.native
@@ -334,7 +335,7 @@ lazy val `kyo-core` =
         )

 lazy val `kyo-offheap` =
-    crossProject(JVMPlatform)
+    crossProject(JVMPlatform, NativePlatform)
         .withoutSuffixFor(JVMPlatform)
         .crossType(CrossType.Full)
         .in(file("kyo-offheap"))

I've added these changes locally and noticed that there are compilation failures. To validate changes, please make sure the tests are passing: sbt kyo-offheapNative/test

[akhilender-bongirwar]

Although I have used the correct imports and syntax as per https://scala-native.org/en/stable/user/interop.html but still I get errors like Not found: unsafe, Not found: type Bool. These basic types are expected to be available from import scala.scalanative.unsafe._.
It seems like the code is not compiling for Scala Native. Could this be due to an issue with the build configuration or missing dependencies?

[akhilender-bongirwar]

I am travelling and currently don't have access to my laptop, I will be back by 21st Feb night.

[sideeffffect]

You still need to align the names with the official Java version.

[akhilender-bongirwar]

Due to the compilation errors, I have modified the MemorySegment.scla file contents to

package java.lang.foreign

import scala.scalanative.libc.stdlib.malloc
import scala.scalanative.libc.string.memcpy
import scala.scalanative.unsafe.*
import scala.scalanative.unsigned.*

/** A minimal stub for Java's MemorySegment using Scala Native pointers.
  *
  * This implementation wraps a pointer along with the allocated size in bytes. It also provides basic support for slicing and for
  * reading/writing primitive values, which are used by the Layout instances in the shared code.
  */
final class MemorySegment private (private[foreign] val ptr: Ptr[Byte], val byteSize: Long):
    /** Creates a new MemorySegment that is a slice of this segment.
      *
      * @param offset
      *   The offset (in bytes) at which the slice begins.
      * @param newSize
      *   The size (in bytes) of the new segment.
      * @return
      *   A new MemorySegment representing the slice.
      */
    def asSlice(offset: Long, newSize: Long): MemorySegment =
        if offset < 0 || newSize < 0 || offset + newSize > byteSize then
            throw new IllegalArgumentException(s"Invalid slice parameters: byteSize=$byteSize, offset=$offset, newSize=$newSize")
        else
            MemorySegment(ptr + offset, newSize)

    /** Reads a value from memory using the provided layout. */
    def get[T](layout: ValueLayout, offset: Long)(using tag: Tag[T]): T =
        require(offset + layout.byteSize <= byteSize)
        !(ptr + offset).asInstanceOf[Ptr[T]]

    /** Writes a value to memory using the provided layout. */
    def set[T](layout: ValueLayout, offset: Long, value: T)(using tag: Tag[T]): Unit =
        require(offset + layout.byteSize <= byteSize)
        !((ptr + offset).asInstanceOf[Ptr[T]]) = value

end MemorySegment

object MemorySegment:

    /** Allocates a new MemorySegment of the given byte size. */
    def allocate(byteSize: Long): MemorySegment =
        val ptr = malloc(byteSize).asInstanceOf[Ptr[Byte]]
        if ptr == null then throw new RuntimeException("malloc returned null")
        new MemorySegment(ptr, byteSize)
    end allocate

    /** Copies a block of memory from the source segment to the destination segment.
      *
      * @param srcSegment
      *   The source MemorySegment.
      * @param srcOffset
      *   The offset (in bytes) into the source segment.
      * @param dstSegment
      *   The destination MemorySegment.
      * @param dstOffset
      *   The offset (in bytes) into the destination segment.
      * @param bytes
      *   The number of bytes to copy.
      */
    def copy(srcSegment: MemorySegment, srcOffset: Long, dstSegment: MemorySegment, dstOffset: Long, bytes: Long): Unit =
        require(srcOffset + bytes <= srcSegment.byteSize)
        require(dstOffset + bytes <= dstSegment.byteSize)
        val _ = memcpy(dstSegment.ptr + dstOffset, srcSegment.ptr + srcOffset, bytes.toCSize)
        ()
    end copy

end MemorySegment

sealed trait ValueLayout:
    val byteSize: Long

object ValueLayout:
    case object JAVA_BOOLEAN extends ValueLayout:
        val byteSize = sizeOf[CBool]
    case object JAVA_BYTE extends ValueLayout:
        val byteSize = sizeOf[Byte]
    case object JAVA_CHAR extends ValueLayout:
        val byteSize = sizeOf[CChar]
    case object JAVA_SHORT extends ValueLayout:
        val byteSize = sizeOf[CShort]
    case object JAVA_INT extends ValueLayout:
        val byteSize = sizeOf[CInt]
    case object JAVA_LONG extends ValueLayout:
        val byteSize = sizeOf[CLong]
    case object JAVA_FLOAT extends ValueLayout:
        val byteSize = sizeOf[CFloat]
    case object JAVA_DOUBLE extends ValueLayout:
        val byteSize = sizeOf[CDouble]
    case object ADDRESS extends ValueLayout:
        val byteSize = sizeOf[Ptr[Byte]]
end ValueLayout

sealed trait AddressLayout extends ValueLayout

Although there are no compilation errors now but there are new errors in MemoryTest.scala

[info] compiling 3 Scala sources to /home/akhil/dev/kyo/kyo-offheap/native/target/scala-3.6.2/classes ...
[info] compiling 2 Scala sources to /home/akhil/dev/kyo/kyo-offheap/native/target/scala-3.6.2/test-classes ...
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:13:23 
[error]  13 |                v   <- mem.get(0)
[error]     |                       ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:299
[error] 299 |                memory.get(JAVA_INT, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:299
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:28:23 
[error]  28 |                _   <- mem.set(0, 42)
[error]     |                       ^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:301
[error] 301 |                memory.set(JAVA_INT, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:301
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:176:27 
[error] 176 |                    _   <- mem.set(0, 42.toByte)
[error]     |                           ^^^^^^^^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:285
[error] 285 |                memory.set(JAVA_BYTE, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:285
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:179:27 
[error] 179 |                    v1  <- mem.get(0)
[error]     |                           ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:283
[error] 283 |                memory.get(JAVA_BYTE, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:283
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:190:27 
[error] 190 |                    _   <- mem.set(0, 1000.toShort)
[error]     |                           ^^^^^^^^^^^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:293
[error] 293 |                memory.set(JAVA_SHORT, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:293
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:193:27 
[error] 193 |                    v1  <- mem.get(0)
[error]     |                           ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:291
[error] 291 |                memory.get(JAVA_SHORT, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:291
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:204:27 
[error] 204 |                    _   <- mem.set(0, 3.14f)
[error]     |                           ^^^^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:317
[error] 317 |                memory.set(JAVA_FLOAT, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:317
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:207:27 
[error] 207 |                    v1  <- mem.get(0)
[error]     |                           ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:315
[error] 315 |                memory.get(JAVA_FLOAT, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:315
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:218:27 
[error] 218 |                    _   <- mem.set(0, 3.14159265359)
[error]     |                           ^^^^^^^^^^^^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:325
[error] 325 |                memory.set(JAVA_DOUBLE, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:325
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:221:27 
[error] 221 |                    v1  <- mem.get(0)
[error]     |                           ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:323
[error] 323 |                memory.get(JAVA_DOUBLE, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:323
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:232:27 
[error] 232 |                    _   <- mem.set(0, 9223372036854775807L)
[error]     |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]     |undefined: memory.set # -1: TermRef(TermRef(NoPrefix,val memory),set) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:309
[error] 309 |                memory.set(JAVA_LONG, offset, value)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:309
[error]  95 |            IO.Unsafe(Unsafe.set(self)(index, value))
[error]     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] -- Error: /home/akhil/dev/kyo/kyo-offheap/shared/src/test/scala/kyo/MemoryTest.scala:235:27 
[error] 235 |                    v1  <- mem.get(0)
[error]     |                           ^^^^^^^^^^
[error]     |undefined: memory.get # -1: TermRef(TermRef(NoPrefix,val memory),get) at inlining
[error]     |---------------------------------------------------------------------------
[error]     |Inline stack trace
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:307
[error] 307 |                memory.get(JAVA_LONG, offset)
[error]     |                ^^^^^^^^^^
[error]     |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[error]     |This location contains code that was inlined from Memory.scala:307
[error]  82 |                val x = Unsafe.get(self)(index)
[error]     |                        ^^^^^^^^^^^^^^^^^^^^^^^
[error]      ---------------------------------------------------------------------------
[error] 12 errors found
[error] (kyo-offheapNative / Test / compileIncremental) Compilation failed

[fwbrasil]

@akhilender-bongirwar if you're having trouble due to the methods being inline, feel free to remove the modifier. We can optimize later.

[akhilender-bongirwar]

@akhilender-bongirwar if you're having trouble due to the methods being inline, feel free to remove the modifier. We can optimize later.

Thx! @fwbrasil. I have modified code accordingly but still trying to figure out one failing test case.

[akhilender-bongirwar]

@fwbrasil done, pls review : )

@fwbrasil one kind request sir, could you please consider increasing the bounty

[sideeffffect]

happy to see the tests pass, great job! 🎉

[sideeffffect]

Still needs more checkOpen to ensure correctness.

[akhilender-bongirwar]

@fwbrasil one kind request sir, could you please consider increasing the bounty

@sideeffffect done!

[fwbrasil]

congrats on your first contribution @akhilender-bongirwar! I've increased the bounty to $250

[fwbrasil]

and thank you @sideeffffect for the help with the reviews 🙏

[akhilender-bongirwar]

congrats on your first contribution @akhilender-bongirwar! I've increased the bounty to $250

Thank you @fwbrasil 🙏 and thank you @sideeffffect 🙏 for reviews and providing relevant official docs links, it truly helped : )

[akhilender-bongirwar]

@fwbrasil @sideeffffect, I've noticed a failing check following the merge of my PR. All checks passed during the PR process, so I'm unsure if this failure is related to my changes. Could you please let me know if it's something I need to address? If so, I'll make the necessary modifications and submit a new PR with your guidance.