NDK Integration (JNI)

Transcription

1 NDK Integration (JNI) Lecture 6 Operating Systems Practical 9 November 2016 This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit OSP NDK Integration (JNI), Lecture 6 1/31

2 JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 2/31

3 Outline JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 3/31

4 JNI Java Native Interface (JNI) Native Programming Interface Allows Java code to interoperate with apps and libraries written in other programming languages When do we use JNI? Java library does not support platform-dependent features Use already existent library written in other language Time-critical code in a low level language (performance) OSP NDK Integration (JNI), Lecture 6 4/31

5 JNI Two-way interface Allows Java apps to invoke native code and vice versa OSP NDK Integration (JNI), Lecture 6 5/31

6 Two-way Interface Support for two types of native code Native libraries Call functions from native libraries In the same way they call Java methods Native applications Embed a Java VM implementation into native apps Execute components written in Java e.g. C web browser executes applets in an embedded Java VM implementation OSP NDK Integration (JNI), Lecture 6 6/31

7 Implications of Using JNI Java apps are portable Run on multiple platforms The native component will not run on multiple platforms Recompile the native code for the new platform Java is type-safe and secure C/C++ are not Misbehaving native code can affect the whole application Security checks when invoking native code Extra care when writing apps that use JNI Native methods in few classes Clean isolation between native code and Java app OSP NDK Integration (JNI), Lecture 6 7/31

8 Android NDK Android Native Development Kit Allows the embed C/C++ (native) code in Android applications Implement your own native code or use existing native libraries ndk-build Shell script that invokes the NDK build scripts Probe the development system and app project file to decide what to build Generate binaries Copy binaries in the app s project path OSP NDK Integration (JNI), Lecture 6 8/31

9 Outline JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 9/31

10 Basic JNI Example - Android.mk Android.mk Configuration file In /jni The name of the native source file: hello-jni.c The name of the shared library to build: hello-jni Built library: libhello-jni.so LOCAL PATH := $ ( c a l l my d i r ) i n c l u d e $ (CLEAR VARS) LOCAL MODULE := h e l l o j n i LOCAL SRC FILES := h e l l o j n i. c i n c l u d e $ (BUILD SHARED LIBRARY) OSP NDK Integration (JNI), Lecture 6 10/31

11 Basic JNI Example - Application.mk Application.mk In /jni Specifies the CPU and architecture for building In this example - all supported architectures APP ABI := a l l OSP NDK Integration (JNI), Lecture 6 11/31

12 Java source code in /src Load native library in a static initializer Declare the native function (native keyword) Call the native function package com. example. h e l l o j n i ; Basic JNI Example - Java code p u b l i c c l a s s H e l l o J n i extends A c t i v i t y O v e r r i d e p u b l i c v o i d o n C r e a t e ( Bundle s a v e d I n s t a n c e S t a t e ) { s u p e r. o n C r e a t e ( s a v e d I n s t a n c e S t a t e ) ; TextView t v = new TextView ( t h i s ) ; t v. s e t T e x t ( s t r i n g F r o m J N I ( ) ) ; s e t C o n t e n t V i e w ( t v ) ; } p u b l i c n a t i v e S t r i n g s t r i n g F r o m J N I ( ) ; s t a t i c { System. l o a d L i b r a r y ( h e l l o j n i ) ; } } OSP NDK Integration (JNI), Lecture 6 12/31

13 Basic JNI Example - Native code C source code in /jni Implements the native function Includes jni.h Function name - based on the Java function name and the path to the file containing it Arguments: JNIEnv * - pointer to the VM, called interface pointer jobject - implicit this object passed from the Java side Creates a string by using a JNI function (NewStringUTF) #i n c l u d e < s t r i n g. h> #i n c l u d e < j n i. h> j s t r i n g J a v a c o m e x a m p l e h e l l o j n i H e l l o J n i s t r i n g F r o m J N I ( JNIEnv env, j o b j e c t t h i z ) { r e t u r n ( env) >NewStringUTF ( env, H e l l o from JNI ) ; } OSP NDK Integration (JNI), Lecture 6 13/31

14 Outline JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 14/31

15 JNIEnv interface pointer Passed into each native method call as the first argument Valid only in the current thread (cannot be used by other threads) Points to a location that contains a pointer to a function table Each entry in the table points to a JNI function Native methods access data structures in the Java VM through JNI functions OSP NDK Integration (JNI), Lecture 6 15/31

16 JNIEnv interface pointer For C and C++ source files the syntax for calling JNI functions differs C code JNIEnv is a pointer to a JNINativeInterface structure Pointer needs to be dereferenced first JNI functions do not know the current JNI environment JNIEnv instance should be passed as the first argument to the function call e.g. return (*env)->newstringutf(env, "Hello!"); C++ code JNIEnv is a C++ class JNI functions exposed as member functions JNI functions have access to the current JNI environment e.g. return env->newstringutf("hello!"); OSP NDK Integration (JNI), Lecture 6 16/31

17 Second Argument Second argument depends whether the method is static or instance Instance methods - can be called only on a class instance Static methods - can be called directly from a static context Both can be declared as native For instance native method Reference to the object on which the method is invoked (this in C++) e.g. jobject thisobject For static native method Reference to the class in which the method is defined e.g. jclass thisclass OSP NDK Integration (JNI), Lecture 6 17/31

18 Outline JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 18/31

19 Mapping of Types JNI defines a set of C/C++ types corresponding to Java types Java types Primitive types: int, float, char Reference types: classes, instances, arrays The two types are treated differently by JNI int -> jint (32 bit integer) float -> jfloat (32 bit floating point number) OSP NDK Integration (JNI), Lecture 6 19/31

20 Primitive Types Java Type JNI Type C/C++ Type Size boolean jboolean unsigned char unsigned 8 bits byte jbyte char signed 8 bits char jchar unsigned short unsigned 16 bits short jshort short signed 16 bits int jint int signed 32 bits long jlong long long signed 64 bits float jfloat float 32 bits double jdouble double 64 bits OSP NDK Integration (JNI), Lecture 6 20/31

21 Objects Objects -> opaque references C pointer to internal data structures in the Java VM Objects accessed using JNI functions (JNIEnv interface pointer) e.g. GetStringUTFChars() function for accessing the contents of a string All JNI references have type jobject All reference types are subtypes of jobject Correspond to the most used types in Java jstring, jobjectarray, etc. OSP NDK Integration (JNI), Lecture 6 21/31

22 Reference Types Java Type java.lang.class java.lang. String java.lang.throwable other objects java.lang.object[] boolean[] byte[] char[] short[] int[] long[] float[] double[] other arrays Native Type jclass jstring jthrowable jobject jobjectarray jbooleanarray jbytearray jchararray jshortarray jintarray jlongarray jfloatarray jdoublearray jarray OSP NDK Integration (JNI), Lecture 6 22/31

23 Outline JNI Android JNI Example Native Method Arguments Mapping of Types Operations on Strings OSP NDK Integration (JNI), Lecture 6 23/31

24 String Types String is a reference type in JNI (jstring) Cannot be used directly as native C strings Need to convert the Java string references into C strings and back No function to modify the contents of a Java string (immutable objects) JNI supports UTF-8 and UTF-16/Unicode encoded strings UTF-8 compatible with 7-bit ASCII UTF-8 strings terminated with \0 char UTF-16/Unicode Two sets of functions jstring is represented in Unicode in the VM OSP NDK Integration (JNI), Lecture 6 24/31

25 Convert C String to Java String NewStringUTF, NewString jstring javastring = env->newstringutf("hello!"); Takes a C string, returns a Java string reference type If the VM cannot allocate memory Returns NULL OutOfMemoryError exception thrown in the VM Native code should not continue OSP NDK Integration (JNI), Lecture 6 25/31

26 Convert Java String to C String GetStringUTFChars, GetStringChars const jbyte* str = env->getstringutfchars(javastring, &iscopy); const jchar* str = env->getstringchars(javastring, &iscopy); iscopy JNI_TRUE - returned string is a copy of the chars in the original instance JNI_FALSE - returned string is a direct pointer to the original instance (pinned object in heap) Pass NULL if it s not important If the string contains only 7-bit ASCII chars you can use printf If the memory allocation fails it returns NULL, throws OutOfMemory exception OSP NDK Integration (JNI), Lecture 6 26/31

27 Release Strings Free memory occupied by the C string ReleaseStringUTFChars, ReleaseStringChars env->releasestringutfchars(javastring, str); String should be released after it is used Avoid memory leaks Frees the copy or unpins the instance (copy or not) OSP NDK Integration (JNI), Lecture 6 27/31

28 Length and Copy in Buffer Get string length GetStringUTFLength/GetStringLength on the jstring Or strlen on the GetStringUTFChars result Copy string elements into a preallocated buffer env->getstringutfregion(javastring, 0, len, buffer); start index and length length can be obtained with GetStringLength buffer is char[] No memory allocation, no out-of-memory checks OSP NDK Integration (JNI), Lecture 6 28/31

29 Critical Region GetStringCritical, ReleaseStringCritical Increase the probability to obtain a direct pointer to the string Critical Section between the calls Must not make blocking operations Must not allocate new objects in the Java VM Disable garbage collection when holding a direct pointer to a string Blocking operations or allocating objects may lead to deadlock No GetStringUTFCritical -> usually makes a copy of the string OSP NDK Integration (JNI), Lecture 6 29/31

30 Bibliography material/jni.pdf guides/jni/spec/jnitoc.html guides/jni/spec/functions.html perf-jni.html Onur Cinar, Pro Android C++ with the NDK, Chapter 3 Sylvain Ratabouil, Android NDK, Beginner s Guide, Chapter 3 OSP NDK Integration (JNI), Lecture 6 30/31

31 Keywords Java Native Interface Two-way interface Native methods Interface pointer Static methods Instance methods Primitive types Reference types JNI functions Opaque reference Java string reference Conversion operations OSP NDK Integration (JNI), Lecture 6 31/31