Class SpartanContextImpl

java.lang.Object
org.spartan.internal.engine.context.SpartanContextImpl
All Implemented Interfaces:
org.spartan.api.engine.context.SpartanContext
public class SpartanContextImpl extends Object implements org.spartan.api.engine.context.SpartanContext
Implementation of SpartanContext using MemorySegment for shared memory with native code. The data is stored in a MemorySegment that C++ can directly read/write. Elements are ordered by index to ensure consistent data order for model training.

Memory Architecture:

  • dataSegment: Contiguous buffer of doubles - flattened element data
  • cleanSizesSegment: Int array for variable element sizes (dynamic slicing)
  • agentIdSegment: Cached agent identifier for native calls
  • slotCountSegment: Cached variable element count for native calls

Zero-GC Hot Path: The update() method is designed to run at high frequency without allocating objects. All iteration uses pre-cached arrays indexed by position.

  • Constructor Details

    • SpartanContextImpl

      public SpartanContextImpl(@NotNull @NotNull String identifier, @NotNull @NotNull Arena arena)

    • SpartanContextImpl

      public SpartanContextImpl(@NotNull @NotNull String identifier, @NotNull @NotNull Arena arena, int initialCapacity)

  • Method Details

    • getData

      @NotNull public @NotNull MemorySegment getData()

    • getArena

      @NotNull public @NotNull Arena getArena()
      Internal: Get the Arena used by this context. This arena is shared across all models using this context,
      Returns:
      the Arena used for memory allocation

    • getSize

      public int getSize()
      Specified by:
      getSize in interface org.spartan.api.engine.context.SpartanContext

    • readDouble

      public double readDouble(int index)
      Specified by:
      readDouble in interface org.spartan.api.engine.context.SpartanContext

    • readDoubles

      public double[] readDoubles(int startIndex, int length)
      Specified by:
      readDoubles in interface org.spartan.api.engine.context.SpartanContext

    • update

      public void update()
      Updates all elements and flattens their data into the shared dataSegment.

      Algorithm:

      1. Rebuild caches if structural modifications occurred
      2. Call update() on each element (computes new data)
      3. Calculate total valid size from all elements
      4. Ensure dataSegment has sufficient capacity
      5. Copy each element's data into dataSegment at correct offset
      6. Write variable element sizes to cleanSizesSegment

      Zero-GC: Uses pre-cached arrays with indexed loops. No iterators, no boxing, no intermediate allocations. Safe to call 20+ times per second per agent.

      Specified by:
      update in interface org.spartan.api.engine.context.SpartanContext

    • syncCleanSizes

      public void syncCleanSizes(long agentIdentifier)
      Synchronizes the clean sizes buffer with the native engine. Call this after update() when the agent is registered with C++.

      This communicates the valid data sizes for each variable element slot, allowing C++ to process only the meaningful portion of variable-length arrays.

      Parameters:
      agentIdentifier - the unique identifier for this agent in the native registry

    • addElement

      public void addElement(@NotNull @NotNull org.spartan.api.engine.context.element.SpartanContextElement element, int index)
      Specified by:
      addElement in interface org.spartan.api.engine.context.SpartanContext

    • removeElement

      public void removeElement(@NotNull @NotNull org.spartan.api.engine.context.element.SpartanContextElement element)
      Specified by:
      removeElement in interface org.spartan.api.engine.context.SpartanContext

    • removeElementsByIdentifier

      public void removeElementsByIdentifier(@NotNull @NotNull String identifier)
      Specified by:
      removeElementsByIdentifier in interface org.spartan.api.engine.context.SpartanContext

    • removeElementsOfType

      public void removeElementsOfType(@NotNull @NotNull Class<? extends org.spartan.api.engine.context.element.SpartanContextElement> type)
      Specified by:
      removeElementsOfType in interface org.spartan.api.engine.context.SpartanContext

    • getElements

      @NotNull public @NotNull Collection<org.spartan.api.engine.context.element.SpartanContextElement> getElements()
      Specified by:
      getElements in interface org.spartan.api.engine.context.SpartanContext

    • getElementsOfType

      @NotNull public <SpartanContextElementType extends org.spartan.api.engine.context.element.SpartanContextElement> @NotNull Collection<SpartanContextElementType> getElementsOfType(@NotNull @NotNull Class<SpartanContextElementType> type)
      Specified by:
      getElementsOfType in interface org.spartan.api.engine.context.SpartanContext

    • getElementByIdentifier

      @NotNull public @NotNull Collection<org.spartan.api.engine.context.element.SpartanContextElement> getElementByIdentifier(@NotNull @NotNull String identifier)
      Specified by:
      getElementByIdentifier in interface org.spartan.api.engine.context.SpartanContext

    • getIdentifier

      @NotNull public @NotNull String getIdentifier()
      Specified by:
      getIdentifier in interface org.spartan.api.engine.context.SpartanContext