MigratingFromJNAToBridJ

How to migrate existing pre-1.0.0-RC1 JavaCL/JNA code to JavaCL/BridJ

What's up ?

JavaCL 1.0-RC and later use [BridJ] as the underlying Java/C interoperability runtime, as opposed to previous 1.0-beta versions that used https://github.com/twall/jna JNA.

The JNA-powered version of JavaCL is still available as a separate download (and as a Maven artifact that has the -jna suffix, like javacl-jna or javacl-core-jna), but you are advised to migrate for some key reasons :

• Lower native call overhead (BridJ beats out JNA in performance)
• BSD-licensed (the JNA version is LGPL-licensed)
• Nicer API, with generic CLBuffer<T> instead of typed buffer classes (CLIntBuffer is now CLBuffer<Integer>)
• All new features will only be introduced into the BridJ version, and some are already specific :
  • the OpenCL-backed UJMP matrix implementation (in the javacl-blas Maven artifact)
  • ScalaCL

Changes needed

As you'll notice by changing the JavaCL JAR or Maven dependency from a 1.0-beta version to a version 1.0-RC or later, there are a few changes to perform in the code to fix the compilation due to the migration from JNA to BridJ :

• Replace CLXXXBuffer by CLBuffer<XXX>
• Replace XXXBuffer.allocate(int) and NIOUtils.directXXXs(int) by Pointer.allocateXXXs(int)
• Replace XXXBuffer.wrap(xxx[]) by [Pointer].pointerToXXXs(xxx[](https://nativelibs4java.sourceforge.net/bridj/api/stable/org/bridj/Pointer.html))
• Replace XXXBuffer by Pointer<XXX>
• Replace Reductor<XXXBuffer> by Reductor<XXX>
• Replace XXXBuffer.equals(...) by Pointer<XXX>.compareTo(...) == 0 (Pointer.equals does not compare pointed memory contents as XXXBuffer.equals does)
• Replace import java.nio.*; by import org.bridj.*;

Mechanical changes

Migrating large JavaCL code bases by hand can be tedious, and doing it with text replacement can be error-prone (especially with the Int vs. Integer naming exceptions).

To ease up the migration, we've prepared the regular expressions you'll need to get almost all of the migration done (the syntax below assumes you're using jEdit, but should be easy to adapt).

Be sure to make a backup of your files and local changes before performing these replacements.

Regular Expressions	Beanshell replace snippets in jEdit
`\bCLIntBuffer\b`	`"CLBuffer"`
`\bCLCharBuffer\b`	`"CLBuffer"`
`\bCL(Long||Short||Double||Float||Byte)Buffer\b`	`"CLBuffer<" + _1 + ">"`
`\b(Int||Char||Long||Short||Double||Float||Byte)Buffer\.allocate\(\b`	`"Pointer.allocate" + _1 + "s("`
`\bNIOUtils\.direct(Int||Char||Long||Short||Double||Float||Byte)s\(\b`	`"Pointer.allocate" + _1 + "s("`
`\b(Int||Char||Long||Short||Double||Float||Byte)Buffer\.wrap\(\b`	`"Pointer.pointerTo" + _1 + "s("`
`\bIntBuffer\b`	`"Pointer"`
`\bCharBuffer\b`	`"Pointer"`
`\b(Long||Short||Double||Float||Byte)Buffer\b`	`"Pointer<" + _1 + ">"`
`\bReductor<(\w*)Buffer>`	`"Reductor<" + _1 + ">"`
`import java.nio.*;`	`"import org.bridj.*;"`