lidavidm commented on code in PR #13788: URL: https://github.com/apache/arrow/pull/13788#discussion_r939014332
########## docs/source/java/cdata.rst: ########## @@ -91,133 +92,379 @@ without writing JNI bindings ourselves. .. code-block:: xml - <?xml version="1.0" encoding="UTF-8"?> - <project xmlns="http://maven.apache.org/POM/4.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <modelVersion>4.0.0</modelVersion> - - <groupId>org.example</groupId> - <artifactId>java-cdata-example</artifactId> - <version>1.0-SNAPSHOT</version> - - <properties> - <maven.compiler.source>8</maven.compiler.source> - <maven.compiler.target>8</maven.compiler.target> - <arrow.version>8.0.0</arrow.version> - </properties> - <dependencies> - <dependency> - <groupId>org.bytedeco</groupId> - <artifactId>javacpp</artifactId> - <version>1.5.7</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-c-data</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-vector</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-memory-core</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-memory-netty</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-format</artifactId> - <version>${arrow.version}</version> - </dependency> - </dependencies> - </project> + <?xml version="1.0" encoding="UTF-8"?> + <project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + + <groupId>org.example</groupId> + <artifactId>java-cdata-example</artifactId> + <version>1.0-SNAPSHOT</version> + + <properties> + <maven.compiler.source>8</maven.compiler.source> + <maven.compiler.target>8</maven.compiler.target> + <arrow.version>9.0.0</arrow.version> + </properties> + <dependencies> + <dependency> + <groupId>org.bytedeco</groupId> + <artifactId>javacpp</artifactId> + <version>1.5.7</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-c-data</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-vector</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-core</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-netty</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-format</artifactId> + <version>${arrow.version}</version> + </dependency> + </dependencies> + </project> .. code-block:: java - import org.bytedeco.javacpp.annotation.Platform; - import org.bytedeco.javacpp.annotation.Properties; - import org.bytedeco.javacpp.tools.InfoMap; - import org.bytedeco.javacpp.tools.InfoMapper; - - @Properties( - target = "CDataJavaToCppExample", - value = @Platform( - include = { - "CDataCppBridge.h" - }, - compiler = {"cpp11"}, - linkpath = {"/arrow/cpp/build/debug/"}, - link = {"arrow"} - ) - ) - public class CDataJavaConfig implements InfoMapper { - - @Override - public void map(InfoMap infoMap) { - } - } + import org.bytedeco.javacpp.annotation.Platform; + import org.bytedeco.javacpp.annotation.Properties; + import org.bytedeco.javacpp.tools.InfoMap; + import org.bytedeco.javacpp.tools.InfoMapper; + + @Properties( + target = "CDataJavaToCppExample", + value = @Platform( + include = { + "CDataCppBridge.h" + }, + compiler = {"cpp11"}, + linkpath = {"/arrow/cpp/build/debug/"}, + link = {"arrow"} + ) + ) + public class CDataJavaConfig implements InfoMapper { + + @Override + public void map(InfoMap infoMap) { + } + } .. code-block:: shell - # Compile our Java code - $ javac -cp javacpp-1.5.7.jar CDataJavaConfig.java + # Compile our Java code + $ javac -cp javacpp-1.5.7.jar CDataJavaConfig.java - # Generate CDataInterfaceLibrary - $ java -jar javacpp-1.5.7.jar CDataJavaConfig.java + # Generate CDataInterfaceLibrary + $ java -jar javacpp-1.5.7.jar CDataJavaConfig.java - # Generate libjniCDataInterfaceLibrary.dylib - $ java -jar javacpp-1.5.7.jar CDataJavaToCppExample.java + # Generate libjniCDataInterfaceLibrary.dylib + $ java -jar javacpp-1.5.7.jar CDataJavaToCppExample.java - # Validate libjniCDataInterfaceLibrary.dylib created - $ otool -L macosx-x86_64/libjniCDataJavaToCppExample.dylib - macosx-x86_64/libjniCDataJavaToCppExample.dylib: - libjniCDataJavaToCppExample.dylib (compatibility version 0.0.0, current version 0.0.0) - @rpath/libarrow.800.dylib (compatibility version 800.0.0, current version 800.0.0) - /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 1200.3.0) - /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0) + # Validate libjniCDataInterfaceLibrary.dylib created + $ otool -L macosx-x86_64/libjniCDataJavaToCppExample.dylib + macosx-x86_64/libjniCDataJavaToCppExample.dylib: + libjniCDataJavaToCppExample.dylib (compatibility version 0.0.0, current version 0.0.0) + @rpath/libarrow.800.dylib (compatibility version 800.0.0, current version 800.0.0) + /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 1200.3.0) + /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0) **Java Test** Let's create a Java class to test our bridge: .. code-block:: java - import org.apache.arrow.c.ArrowArray; - import org.apache.arrow.c.ArrowSchema; - import org.apache.arrow.c.Data; - import org.apache.arrow.memory.BufferAllocator; - import org.apache.arrow.memory.RootAllocator; - import org.apache.arrow.vector.BigIntVector; - - public class TestCDataInterface { - public static void main(String[] args) { - try( - BufferAllocator allocator = new RootAllocator(); - ArrowSchema arrowSchema = ArrowSchema.allocateNew(allocator); - ArrowArray arrowArray = ArrowArray.allocateNew(allocator) - ){ - CDataJavaToCppExample.FillInt64Array( - arrowSchema.memoryAddress(), arrowArray.memoryAddress()); - try( - BigIntVector bigIntVector = (BigIntVector) Data.importVector( - allocator, arrowArray, arrowSchema, null) - ){ - System.out.println("C++-allocated array: " + bigIntVector); - } - } - } - } + import org.apache.arrow.c.ArrowArray; + import org.apache.arrow.c.ArrowSchema; + import org.apache.arrow.c.Data; + import org.apache.arrow.memory.BufferAllocator; + import org.apache.arrow.memory.RootAllocator; + import org.apache.arrow.vector.BigIntVector; + + public class TestCDataInterface { + public static void main(String[] args) { + try( + BufferAllocator allocator = new RootAllocator(); + ArrowSchema arrowSchema = ArrowSchema.allocateNew(allocator); + ArrowArray arrowArray = ArrowArray.allocateNew(allocator) + ){ + CDataJavaToCppExample.FillInt64Array( + arrowSchema.memoryAddress(), arrowArray.memoryAddress()); + try( + BigIntVector bigIntVector = (BigIntVector) Data.importVector( + allocator, arrowArray, arrowSchema, null) + ){ + System.out.println("C++-allocated array: " + bigIntVector); + } + } + } + } + +.. code-block:: shell + + C++-allocated array: [1, 2, 3, null, 5, 6, 7, 8, 9, 10] + +Share an Int32 array from Java to C++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Java Side** + +For this example, we will build a JAR with all dependencies bundled. + +.. code-block:: xml + + <?xml version="1.0" encoding="UTF-8"?> + <project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <groupId>org.example</groupId> + <artifactId>cpptojava</artifactId> + <version>1.0-SNAPSHOT</version> + <properties> + <maven.compiler.source>8</maven.compiler.source> + <maven.compiler.target>8</maven.compiler.target> + <arrow.version>9.0.0</arrow.version> + </properties> + <dependencies> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-c-data</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-netty</artifactId> + <version>${arrow.version}</version> + </dependency> + </dependencies> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-assembly-plugin</artifactId> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>single</goal> + </goals> + <configuration> + <descriptorRefs> + <descriptorRef>jar-with-dependencies</descriptorRef> + </descriptorRefs> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> + </project> + +.. code-block:: java + + import org.apache.arrow.c.ArrowArray; + import org.apache.arrow.c.ArrowSchema; + import org.apache.arrow.c.Data; + import org.apache.arrow.memory.BufferAllocator; + import org.apache.arrow.memory.RootAllocator; + import org.apache.arrow.vector.FieldVector; + import org.apache.arrow.vector.IntVector; + import org.apache.arrow.vector.VectorSchemaRoot; + + import java.util.Arrays; + + public class ToBeCalledByCpp { + final static BufferAllocator allocator = new RootAllocator(); + + /** + * Create a {@link FieldVector} and export this to an existing memory address Review Comment: ```suggestion * Create a {@link FieldVector} and export it via the C Data Interface ``` ########## docs/source/java/cdata.rst: ########## @@ -91,133 +92,379 @@ without writing JNI bindings ourselves. .. code-block:: xml - <?xml version="1.0" encoding="UTF-8"?> - <project xmlns="http://maven.apache.org/POM/4.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <modelVersion>4.0.0</modelVersion> - - <groupId>org.example</groupId> - <artifactId>java-cdata-example</artifactId> - <version>1.0-SNAPSHOT</version> - - <properties> - <maven.compiler.source>8</maven.compiler.source> - <maven.compiler.target>8</maven.compiler.target> - <arrow.version>8.0.0</arrow.version> - </properties> - <dependencies> - <dependency> - <groupId>org.bytedeco</groupId> - <artifactId>javacpp</artifactId> - <version>1.5.7</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-c-data</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-vector</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-memory-core</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-memory-netty</artifactId> - <version>${arrow.version}</version> - </dependency> - <dependency> - <groupId>org.apache.arrow</groupId> - <artifactId>arrow-format</artifactId> - <version>${arrow.version}</version> - </dependency> - </dependencies> - </project> + <?xml version="1.0" encoding="UTF-8"?> + <project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + + <groupId>org.example</groupId> + <artifactId>java-cdata-example</artifactId> + <version>1.0-SNAPSHOT</version> + + <properties> + <maven.compiler.source>8</maven.compiler.source> + <maven.compiler.target>8</maven.compiler.target> + <arrow.version>9.0.0</arrow.version> + </properties> + <dependencies> + <dependency> + <groupId>org.bytedeco</groupId> + <artifactId>javacpp</artifactId> + <version>1.5.7</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-c-data</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-vector</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-core</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-netty</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-format</artifactId> + <version>${arrow.version}</version> + </dependency> + </dependencies> + </project> .. code-block:: java - import org.bytedeco.javacpp.annotation.Platform; - import org.bytedeco.javacpp.annotation.Properties; - import org.bytedeco.javacpp.tools.InfoMap; - import org.bytedeco.javacpp.tools.InfoMapper; - - @Properties( - target = "CDataJavaToCppExample", - value = @Platform( - include = { - "CDataCppBridge.h" - }, - compiler = {"cpp11"}, - linkpath = {"/arrow/cpp/build/debug/"}, - link = {"arrow"} - ) - ) - public class CDataJavaConfig implements InfoMapper { - - @Override - public void map(InfoMap infoMap) { - } - } + import org.bytedeco.javacpp.annotation.Platform; + import org.bytedeco.javacpp.annotation.Properties; + import org.bytedeco.javacpp.tools.InfoMap; + import org.bytedeco.javacpp.tools.InfoMapper; + + @Properties( + target = "CDataJavaToCppExample", + value = @Platform( + include = { + "CDataCppBridge.h" + }, + compiler = {"cpp11"}, + linkpath = {"/arrow/cpp/build/debug/"}, + link = {"arrow"} + ) + ) + public class CDataJavaConfig implements InfoMapper { + + @Override + public void map(InfoMap infoMap) { + } + } .. code-block:: shell - # Compile our Java code - $ javac -cp javacpp-1.5.7.jar CDataJavaConfig.java + # Compile our Java code + $ javac -cp javacpp-1.5.7.jar CDataJavaConfig.java - # Generate CDataInterfaceLibrary - $ java -jar javacpp-1.5.7.jar CDataJavaConfig.java + # Generate CDataInterfaceLibrary + $ java -jar javacpp-1.5.7.jar CDataJavaConfig.java - # Generate libjniCDataInterfaceLibrary.dylib - $ java -jar javacpp-1.5.7.jar CDataJavaToCppExample.java + # Generate libjniCDataInterfaceLibrary.dylib + $ java -jar javacpp-1.5.7.jar CDataJavaToCppExample.java - # Validate libjniCDataInterfaceLibrary.dylib created - $ otool -L macosx-x86_64/libjniCDataJavaToCppExample.dylib - macosx-x86_64/libjniCDataJavaToCppExample.dylib: - libjniCDataJavaToCppExample.dylib (compatibility version 0.0.0, current version 0.0.0) - @rpath/libarrow.800.dylib (compatibility version 800.0.0, current version 800.0.0) - /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 1200.3.0) - /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0) + # Validate libjniCDataInterfaceLibrary.dylib created + $ otool -L macosx-x86_64/libjniCDataJavaToCppExample.dylib + macosx-x86_64/libjniCDataJavaToCppExample.dylib: + libjniCDataJavaToCppExample.dylib (compatibility version 0.0.0, current version 0.0.0) + @rpath/libarrow.800.dylib (compatibility version 800.0.0, current version 800.0.0) + /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 1200.3.0) + /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0) **Java Test** Let's create a Java class to test our bridge: .. code-block:: java - import org.apache.arrow.c.ArrowArray; - import org.apache.arrow.c.ArrowSchema; - import org.apache.arrow.c.Data; - import org.apache.arrow.memory.BufferAllocator; - import org.apache.arrow.memory.RootAllocator; - import org.apache.arrow.vector.BigIntVector; - - public class TestCDataInterface { - public static void main(String[] args) { - try( - BufferAllocator allocator = new RootAllocator(); - ArrowSchema arrowSchema = ArrowSchema.allocateNew(allocator); - ArrowArray arrowArray = ArrowArray.allocateNew(allocator) - ){ - CDataJavaToCppExample.FillInt64Array( - arrowSchema.memoryAddress(), arrowArray.memoryAddress()); - try( - BigIntVector bigIntVector = (BigIntVector) Data.importVector( - allocator, arrowArray, arrowSchema, null) - ){ - System.out.println("C++-allocated array: " + bigIntVector); - } - } - } - } + import org.apache.arrow.c.ArrowArray; + import org.apache.arrow.c.ArrowSchema; + import org.apache.arrow.c.Data; + import org.apache.arrow.memory.BufferAllocator; + import org.apache.arrow.memory.RootAllocator; + import org.apache.arrow.vector.BigIntVector; + + public class TestCDataInterface { + public static void main(String[] args) { + try( + BufferAllocator allocator = new RootAllocator(); + ArrowSchema arrowSchema = ArrowSchema.allocateNew(allocator); + ArrowArray arrowArray = ArrowArray.allocateNew(allocator) + ){ + CDataJavaToCppExample.FillInt64Array( + arrowSchema.memoryAddress(), arrowArray.memoryAddress()); + try( + BigIntVector bigIntVector = (BigIntVector) Data.importVector( + allocator, arrowArray, arrowSchema, null) + ){ + System.out.println("C++-allocated array: " + bigIntVector); + } + } + } + } + +.. code-block:: shell + + C++-allocated array: [1, 2, 3, null, 5, 6, 7, 8, 9, 10] + +Share an Int32 array from Java to C++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Java Side** + +For this example, we will build a JAR with all dependencies bundled. + +.. code-block:: xml + + <?xml version="1.0" encoding="UTF-8"?> + <project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <groupId>org.example</groupId> + <artifactId>cpptojava</artifactId> + <version>1.0-SNAPSHOT</version> + <properties> + <maven.compiler.source>8</maven.compiler.source> + <maven.compiler.target>8</maven.compiler.target> + <arrow.version>9.0.0</arrow.version> + </properties> + <dependencies> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-c-data</artifactId> + <version>${arrow.version}</version> + </dependency> + <dependency> + <groupId>org.apache.arrow</groupId> + <artifactId>arrow-memory-netty</artifactId> + <version>${arrow.version}</version> + </dependency> + </dependencies> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-assembly-plugin</artifactId> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>single</goal> + </goals> + <configuration> + <descriptorRefs> + <descriptorRef>jar-with-dependencies</descriptorRef> + </descriptorRefs> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> + </project> + +.. code-block:: java + + import org.apache.arrow.c.ArrowArray; + import org.apache.arrow.c.ArrowSchema; + import org.apache.arrow.c.Data; + import org.apache.arrow.memory.BufferAllocator; + import org.apache.arrow.memory.RootAllocator; + import org.apache.arrow.vector.FieldVector; + import org.apache.arrow.vector.IntVector; + import org.apache.arrow.vector.VectorSchemaRoot; + + import java.util.Arrays; + + public class ToBeCalledByCpp { + final static BufferAllocator allocator = new RootAllocator(); + + /** + * Create a {@link FieldVector} and export this to an existing memory address + * @param schemaAddress Schema memory address to wrap + * @param arrayAddress Array memory address to wrap + */ + public static void fillVector(long schemaAddress, long arrayAddress){ + try (ArrowArray arrow_array = ArrowArray.wrap(arrayAddress); + ArrowSchema arrow_schema = ArrowSchema.wrap(schemaAddress) ) { + Data.exportVector(allocator, populateFieldVectorToExport(), null, arrow_array, arrow_schema); + } + } + + /** + * Create a {@link VectorSchemaRoot} and export this to an existing memory address Review Comment: ```suggestion * Create a {@link VectorSchemaRoot} and export it via the C Data Interface ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
