[GR-49386] [GR-38404] Convert guest byte buffers to host byte array or ByteSequence.

PullRequest: graal/15821

Author: jchalou

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/ffi/TruffleByteBuffer.java

@@ -167,6 +167,21 @@ byte readBufferByte(long byteOffset, @Shared("error") @Cached BranchProfile erro
         }
     }
 
+    @ExportMessage
+    void readBuffer(long byteOffset, byte[] destination, int destinationOffset, int length, @Shared("error") @Cached BranchProfile error) throws InvalidBufferOffsetException {
+        if (length < 0) {
+            error.enter();
+            throw InvalidBufferOffsetException.create(byteOffset, length);
+        }
+        try {
+            int index = Math.toIntExact(byteOffset);
+            readBytes(this.byteBuffer, index, destination, destinationOffset, length);
+        } catch (ArithmeticException | IndexOutOfBoundsException e) {
+            error.enter();
+            throw InvalidBufferOffsetException.create(byteOffset, length);
+        }
+    }
+
     @ExportMessage
     void writeBufferByte(long byteOffset, byte value, @Shared("error") @Cached BranchProfile error) throws UnsupportedMessageException, InvalidBufferOffsetException {
         try {
@@ -311,6 +326,11 @@ private static byte readByte(ByteBuffer byteBuffer, int index) {
         return byteBuffer.get(index);
     }
 
+    @TruffleBoundary(allowInlining = true)
+    private static void readBytes(ByteBuffer byteBuffer, int index, byte[] destination, int destinationOffset, int length) {
+        byteBuffer.get(index, destination, destinationOffset, length);
+    }
+
     @TruffleBoundary(allowInlining = true)
     private static short readShort(ByteBuffer byteBuffer, ByteOrder order, int index) {
         return byteBuffer.order(order).asShortBuffer().get(index);

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/messages/InteropMessage.java

@@ -125,6 +125,7 @@ public enum Message {
         IsBufferWritable,
         GetBufferSize,
         ReadBufferByte,
+        ReadBuffer,
         WriteBufferByte,
         ReadBufferShort,
         WriteBufferShort,

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/staticobject/SharedInterop.java

@@ -1358,6 +1358,23 @@ public static byte readBufferByte(StaticObject receiver, long byteOffset,
         throw unsupported();
     }
 
+    @ExportMessage
+    public static void readBuffer(StaticObject receiver, long byteOffset, byte[] destination, int destinationOffset, int length,
+                    @Cached IndirectCallNode callNode,
+                    @Cached CallSharedInteropMessage sharedCallNode) throws UnsupportedMessageException {
+        int dispatchId = receiver.getKlass().getDispatchId();
+        InteropMessage.Message message = InteropMessage.Message.ReadBuffer;
+        if (InteropMessageFactories.isShareable(dispatchId, message)) {
+            dispatchId = InteropMessageFactories.sourceDispatch(dispatchId, message);
+            sharedCallNode.call(dispatchId, message, receiver, byteOffset, destination, destinationOffset, length);
+        }
+        CallTarget target = getTarget(receiver, InteropMessage.Message.ReadBuffer);
+        if (target != null) {
+            callNode.call(target, receiver, byteOffset, destination, destinationOffset, length);
+        }
+        throw unsupported();
+    }
+
     @ExportMessage
     public static void writeBufferByte(StaticObject receiver, long byteOffset, byte value,
                     @Cached IndirectCallNode callNode,

sdk/CHANGELOG.md

@@ -4,6 +4,10 @@ This changelog summarizes major changes between GraalVM SDK versions. The main f
 
 ## Version 24.0.0
 * (GR-49334) Deprecated the `FileSystems#allowLanguageHomeAccess()` method and introduced `FileSystem#allowInternalResourceAccess()` as a replacement. To ensure compatibility, both methods now provide support for language homes and internal resources.
+* (GR-49386) Added `Value#readBuffer(long, byte[], int, int)` to enable bulk reads of buffers into byte arrays.
+* (GR-49386) Added the ability to use `Value#as(ByteSequence.class)` to map guest language byte buffers (`Value#hasBufferElements()`) to the read-only `ByteSequence` interface in order to access the bytes without copying the guest language buffer.
+* (GR-49386) Custom implementations of `ByteSequence`, like the values returned by `ByteSequence.create(byte[])`, are now interpreted by guest languages as buffers.
+* (GR-38404) Added the ability to use `Value#as(Collection.class)` to map guest language arrays (`Value#hasArrayElements()`) to the `Collection` interface in order to access the array elements without copying the guest language array.
 
 ## Version 23.1.0
 * (GR-43819) The GraalVM SDK was split into several more fine-grained modules. The use of the graalvm-sdk module is now deprecated. Please update your Maven and module dependencies accordingly. Note that all APIs remain compatible. The following new modules are available:

sdk/src/org.graalvm.polyglot/snapshot.sigtest

@@ -634,6 +634,7 @@ meth public static org.graalvm.polyglot.Value asValue(java.lang.Object)
 meth public void pin()
 meth public void putHashEntry(java.lang.Object,java.lang.Object)
 meth public void putMember(java.lang.String,java.lang.Object)
+meth public void readBuffer(long,byte[],int,int)
 meth public void setArrayElement(long,java.lang.Object)
 meth public void writeBufferByte(long,byte)
 meth public void writeBufferDouble(java.nio.ByteOrder,long,double)

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Engine.java

@@ -1161,6 +1161,21 @@ public ByteSequence asByteSequence(Object origin) {
             return (ByteSequence) origin;
         }
 
+        @Override
+        public Object toByteSequence(Object origin) {
+            return Engine.getImpl().asByteSequence(origin);
+        }
+
+        @Override
+        public int byteSequenceLength(Object origin) {
+            return ((ByteSequence) origin).length();
+        }
+
+        @Override
+        public byte byteSequenceByteAt(Object origin, int index) {
+            return ((ByteSequence) origin).byteAt(index);
+        }
+
         @Override
         public boolean isInstrument(Object instrument) {
             return instrument instanceof Instrument;
@@ -1606,6 +1621,11 @@ public Class<?> getPolyglotExceptionClass() {
             return PolyglotException.class;
         }
 
+        @Override
+        public Class<?> getByteSequenceClass() {
+            return ByteSequence.class;
+        }
+
         @Override
         public Object callContextAsValue(Object current, Object classOverrides) {
             return ((Context) current).asValue(classOverrides);
@@ -2115,6 +2135,11 @@ public FileSystem newNIOFileSystem(java.nio.file.FileSystem fileSystem) {
             throw noPolyglotImplementationFound();
         }
 
+        @Override
+        public ByteSequence asByteSequence(Object object) {
+            throw noPolyglotImplementationFound();
+        }
+
         @Override
         public ProcessHandler newDefaultProcessHandler() {
             throw noPolyglotImplementationFound();

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/HostAccess.java

@@ -301,6 +301,7 @@ public final class HostAccess {
     public enum MutableTargetMapping {
         /**
          * Enables default mapping of guest object arrays to host object {@link java.util.List}.
+         * This mapping is also applied when the target host object is {@link java.util.Collection}.
          */
         ARRAY_TO_JAVA_LIST,
         /**

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Value.java

@@ -464,6 +464,55 @@ public byte readBufferByte(long byteOffset) throws UnsupportedOperationException
         return dispatch.readBufferByte(this.context, receiver, byteOffset);
     }
 
+    /**
+     * Reads bytes from the receiver object into the specified byte array.
+     * <p>
+     * The access is <em>not</em> guaranteed to be atomic. Therefore, this message is <em>not</em>
+     * thread-safe.
+     * <p>
+     * Invoking this message does not cause any observable side-effects.
+     * <p>
+     * <b>Example</b> reading into an output stream using a 4k auxiliary byte array:
+     * 
+     * <pre>
+     * Value val = ...
+     * assert val.hasBufferElements();
+     * try (OutputStream out = ...) {
+     *     byte[] aux = new byte[4096];
+     *     long bufferSize = val.getBufferSize();
+     *     for (long offset = 0; offset < bufferSize; offset += aux.length) {
+     *         int bytesToRead = (int) Math.min(bufferSize - offset, aux.length);
+     *         val.readBuffer(offset, aux, 0, bytesToRead);
+     *         out.write(aux, 0, bytesToRead);
+     *     }
+     * }
+     * </pre>
+     *
+     * In case the goal is to read the whole contents into a single byte array, the easiest way is
+     * to do that through {@link org.graalvm.polyglot.io.ByteSequence}:
+     * 
+     * <pre>
+     * byte[] byteArray = val.as(ByteSequence.class).toByteArray();
+     * </pre>
+     * 
+     * @param byteOffset offset in the buffer to start reading from.
+     * @param destination byte array to write the read bytes into.
+     * @param destinationOffset offset in the destination array to start writing from.
+     * @param length number of bytes to read.
+     * @throws IndexOutOfBoundsException if and only if
+     *             <code>byteOffset < 0 || length < 0 || byteOffset + length > </code>{@link #getBufferSize()}<code> || destinationOffset < 0 || destinationOffset + length > destination.length</code>
+     * @throws UnsupportedOperationException if the value does not have {@link #hasBufferElements
+     *             buffer elements}.
+     * @throws IllegalStateException if the context is already closed.
+     * @throws PolyglotException if a guest language error occurred during execution.
+     * @since 24.0
+     */
+    public void readBuffer(long byteOffset, byte[] destination, int destinationOffset, int length) throws UnsupportedOperationException, IndexOutOfBoundsException {
+        Objects.requireNonNull(destination, "destination");
+        Objects.checkFromIndexSize(destinationOffset, length, destination.length);
+        dispatch.readBuffer(this.context, receiver, byteOffset, destination, destinationOffset, length);
+    }
+
     /**
      * Writes the given byte at the given byte offset from the start of the buffer.
      * <p>

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/impl/AbstractPolyglotImpl.java

@@ -286,8 +286,16 @@ protected APIAccess() {
 
         public abstract boolean isByteSequence(Object origin);
 
+        public abstract Class<?> getByteSequenceClass();
+
         public abstract ByteSequence asByteSequence(Object origin);
 
+        public abstract Object toByteSequence(Object origin);
+
+        public abstract int byteSequenceLength(Object origin);
+
+        public abstract byte byteSequenceByteAt(Object origin, int index);
+
         public abstract boolean isProxyArray(Object proxy);
 
         public abstract boolean isProxyDate(Object proxy);
@@ -953,6 +961,8 @@ protected AbstractHostAccess(AbstractPolyglotImpl impl) {
 
         public abstract <T> List<T> toList(Object internalContext, Object guestValue, boolean implementFunction, Class<T> elementClass, Type elementType);
 
+        public abstract Object toByteSequence(Object internalContext, Object guestValue);
+
         public abstract <K, V> Map<K, V> toMap(Object internalContext, Object foreignObject, boolean implementsFunction, Class<K> keyClass, Type keyType, Class<V> valueClass, Type valueType);
 
         public abstract <K, V> Map.Entry<K, V> toMapEntry(Object internalContext, Object foreignObject, boolean implementsFunction,
@@ -1112,6 +1122,8 @@ public boolean hasBufferElements(Object context, Object receiver) {
 
         public abstract byte readBufferByte(Object context, Object receiver, long byteOffset);
 
+        public abstract void readBuffer(Object context, Object receiver, long byteOffset, byte[] destination, int destinationOffset, int length);
+
         public abstract void writeBufferByte(Object context, Object receiver, long byteOffset, byte value);
 
         public abstract short readBufferShort(Object context, Object receiver, ByteOrder order, long byteOffset);
@@ -1401,6 +1413,10 @@ public FileSystem newNIOFileSystem(java.nio.file.FileSystem fileSystem) {
         return getNext().newNIOFileSystem(fileSystem);
     }
 
+    public ByteSequence asByteSequence(Object object) {
+        return getNext().asByteSequence(object);
+    }
+
     public ProcessHandler newDefaultProcessHandler() {
         return getNext().newDefaultProcessHandler();
     }

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/impl/UnnamedToModuleBridge.java

@@ -418,6 +418,13 @@ static FileSystem fromFileSystem(Object value) {
             return new UnnamedToModuleFileSystemGen(value);
         }
 
+        static ByteSequence fromByteSequence(Object value) {
+            if (value == null) {
+                return null;
+            }
+            return new UnnamedToModuleByteSequenceGen(value);
+        }
+
         static ThreadScope fromThreadScope(Object value) {
             if (value == null) {
                 return null;