Where Not to Use Native Code

The biggest and most common false assumption about native code is the expectation of an automatic performance gain by simply coding application modules in native code instead of Java.

Using native machine code does not always result in an automatic performance boost. Although earlier versions of Java were known to be much slower than native code, the latest Java technology is highly optimized, and the speed difference is negligible in many cases. The JIT compilation feature of the Java Virtual Machine, specifically the Dalvik VM in the case of Android, allows the translation from the interpreted byte-code into machine code during application startup. The translated machine code is then used throughout the execution of the application, making the Java applications run as fast as their native counterparts.

Be aware that overusing the native code support in your application can easily lead to much bigger stability problems. Because native code is not managed by the Dalvik VM, most of that memory management code has to be written by you; and this itself increases the complexity and the code size of the overall application.

Where to Use Native Code

Using native code in Android applications is definitely not a bad practice. In certain cases, it becomes highly beneficial because it can provide for code reuse and improve the performance of some complex applications. Here is a list of some common areas that can benefit from native code support:

• Use of Existing Third Party Libraries: Imagine that you will be developing a Video Editing application on the Android platform. For your application to operate, it needs to be able to read and write in various video formats, such as the Theora video codec. The Java framework does not provide any APIs to deal with Theora. Developing the code necessary to deal with this video format is not an efficient use of time, so your best option is to utilize an already available third-party library that can understand the Theora video codec. Despite the popularity of the Java programming language, the code library ecosystem is still highly mandated by C/C++-based native code libraries. There is a much better chance that you will find various implementations of the Theora video codec as C/C++ libraries. Native code support becomes really handy here, as it can enable you to blend the native C/C++ library into your Android application seamlessly. It is a good practice to use native code support to promote code reuse, as that facilitates the development process.
• Hardware Specific Optimization of Performance Critical Code: As a platform-independent programming language, Java does not provide any mechanism for using the CPU-specific features for optimizing the performance-critical portions of Android applications. Compared to desktop platforms, mobile device resources are highly scarce. For complex applications with high performance requirements, such as 3D games and multimedia applications, effectively using every possible CPU feature is crucial. ARM processors, such as ARM NEON and ARM VFPv3-D32, provide additional instruction sets to allow mobile applications to hardware-accelerate many performance-critical operations. It is a good practice to use native code support to benefit from these CPU specific features.

Difficulties Writing Native Code Using JNI

Integrating native code into a Java application through JNI requires native functions to be declared with a specially crafted name conforming to JNI specification. In addition to the function name, each parameter to the native function should also use the JNI data types. Because the Java and the native code are compiled in separate silos, any issues in this part of the code are not visible at compile-time.

Reaching back from native code to Java space also requires a sequence of API calls. As the native programming language has no knowledge about the Java portion of the code, it cannot provide any compile-time errors if you use a wrong API call. In addition, a change in the Java portion of the code could also break the native portion of the code, and you would not be informed about this at compile-time, either.

Even if you take extraordinary measures to prevent bugs from occurring, keeping native methods and their declarations in Java space aligned can be a cumbersome and redundant task. In this section, you will learn how to benefit from the available tools to auto-generate the necessary code instead of typing it manually.

Generate the Code Using a Tool

A common good practice in almost every programming language is that as a good developer, you should always minimize the number of code lines you manually produce. Any code line that you produce, you will have to maintain throughout the lifetime of your application. As a good practice, you should always take advantage of the code generators that are provided by the SDKs and the IDEs to achieve that.

JNIEXPORT jstring JNICALL Java_com_apress_example_Unix_getlogin(JNIEnv* env, jclass clazz) {
    jstring loginString = 0;

    const char* login = getlogin();
    if (0 != login) {
        loginString = env->NewStringUTF(login);
    }

    return loginString;
}

/* Module name is Unix. */
%module Unix

%{
/* Include the POSIX operating system APIs. */
#include <unistd.h>
%}

/* Ask SWG to wrap getlogin function. */
extern char* getlogin(void);

swig -java
     -package com.apress.example
     -outdir src/com/apress/example
     jni/Unix.i

/* ----------------------------------------------------------------------------
 * This file was automatically generated by SWIG (http://www.swig.org).
 * Version 2.0.11
 *
 * This file is not intended to be easily readable and contains a number of
 * coding conventions designed to improve portability and efficiency. Do not make
 * changes to this file unless you know what you are doing--modify the SWIG
 * interface file instead.
 * ----------------------------------------------------------------------------- */

#define SWIGJAVA

...
  
/* Include the POSIX operating system APIs. */
#include <unistd.h>

 
#ifdef __cplusplus
extern "C" {
#endif

SWIGEXPORT jstring JNICALL Java_com_apress_example_UnixJNI_getlogin(JNIEnv *jenv, jclass jcls) {
  jstring jresult = 0 ;
  char *result = 0 ;
   
  (void)jenv;
  (void)jcls;
  result = (char *)getlogin();
  if (result) jresult = (*jenv)->NewStringUTF(jenv, (const char *)result);
  return jresult;
}

...

Minimize the Number of JNI API Calls

Although SWIG tool is highly promising, needless to say there will be still cases where automatic code generation is simply not an option. In those cases, you will need to write the necessary JNI API calls to provide the functionality. Even when manual JNI API calls cannot be prevented, minimizing the number of such calls can still help in optimizing the overall application and reducing the code footprint. In this section you will learn about some of the best practices to minimize the number of JNI API calls needed in your application.

JNIEXPORT void JNICALL Java_com_apress_example_Unix_method(JNIEnv* env, jobject obj) {

    jclass clazz = env->GetObjectClass(obj);
     
    jfieldID field1Id = env->GetFieldID(clazz, "field1", "Ljava/lang/String;");
    jstring field1Value = env->GetObjectField(obj, field1Id);
     
    jfieldID field2Id = env->GetFieldID(clazz, "field2", "Ljava/lang/Integer;");
    jobject field2Value = env->GetObjectField(obj, field2Id);

    ...
}

JNIEXPORT jstring JNICALL Java_com_apress_example_Unix_method(JNIEnv* env, jobject obj,
    jstring field1, jobject field2) {
    ...
}

public void method() {
    jniMethod(field1, field2);
}

public native void jniMethod(String field1, Integer field2);

Memory Usage

Compared to desktop-based platforms, memory is a scarce resource on mobile devices. Java is known as a managed programming language, meaning that the Java Virtual Machine (JVM) manages the application memory on behalf of the developer. During the execution of an application, JVM keeps an eye on the available references to the allocated memory regions. When JVM detects that an allocated memory region can no longer be reached by the application code, it releases the memory automatically through a mechanism known as garbage collection. This frees the developer from managing the application memory directly, and it drastically reduces the complexity of the code.

JVM garbage collectors boundaries are limited to the Java space only. Because the native code does not run in the managed environment, the JVM garbage collector cannot monitor or free the memory that your application allocates in the native space. It is the developer’s responsibility to manage the application memory in native space properly. Otherwise, the application can easily cause the device to run out of memory. This can jeopardize the stability of both the application and the device.

In this section, you will learn about some of the best practices for using memory efficiently in the native space.

jobject globalObject = env->NewGlobalRef(localObject);
if (0 != globalObject) {
    // You can now cache and reuse globalObject
}

env->DeleteLocalRef(globalObject);

jsize len = env->GetArrayLength(nameArray); // len = 600

for (jsize i=0; i < len; i++) {
    jstring name = env->GetObjectArrayElement(nameArray, i);
    ...
}

jsize len = env->GetArrayLength(nameArray);

for (jsize i=0; i < len; i++) {
    jstring name = env->GetObjectArrayElement(nameArray, i);
    ...
    env->DeleteLocalRef(name);
}

const jbyte* str;
jboolean isCopy;

str = env->GetStringUTFChars(javaString, &isCopy);
if (0 != str) {
    /* You can use the string as an ordinary C string. */
}

const jbyte* str;
jboolean isCopy;

str = env->GetStringUTFChars(javaString, &isCopy);
if (0 != str) {
    /* You can use the string as an ordinary C string. */

    env->ReleaseStringUTFChars(javaString, str);
    str = 0;
}

jsize len = env->GetArrayLength(stockQuotesArray); // len = 1000

jint* stockQuotes = env->GetIntArrayElements(stockQuotesArray, 0);

stockQuotes[0] = 1;
stockQuotes[1] = 2;

env->ReleaseIntArrayElements(stockQuotesArray, stockQuotes, 0);

jint stockQuotes[2];

env->GetIntArrayRegion(stockQuotesArray, 0, 2, stockQuotes);

stockQuotes[0] = 1;
stockQuotes[1] = 2;

env->SetIntArrayRegion(stockQuotesArray, 0, 2, stockQuotes);

void Release<Type>ArrayElements(JNIEnv* env, ArrayType array,
        NativeType* elements, jint mode );

unsigned char* buffer;
buffer = (unsigned char*) env->GetDirectBufferAddress(directBuffer);

Caching Classes, Method and Field IDs

JNI does not expose the fields and methods of Java classes directly in the native code. Instead, it provides a set of APIs to access them indirectly. For example, to get the value of a field of a class, the following steps will be taken:

1. Obtain a reference to the class object, through the FindClass function.
2. Obtain the ID for the field that will be accessed, through the GetFieldID function.
3. Obtain the actual value of the field by supplying the class instance and the field ID to the Get<Type>Field function.

Although they are used very frequently in JNI applications, both the GetFieldID and GetMethodID functions are very heavy function calls by their nature. As you would imagine, these functions have to traverse through the entire inheritance chain for the class to identify the right ID to return. Because neither the Class object, the Class inheritance, nor the field ID can change during the execution of the application, those values can actually be cached in the native layer for subsequent access with fewer API calls.

The return type of the FindClass function is a local reference. In order to cache that, you will need to create a global reference first through the NewGlobalRef function. On the other hand, the return value of GetFieldID is jfieldID, which is simply an integer, and it can be cached as is.

As a good practice, you should focus on caching both the field and method IDs for the pieces that are accessed multiple times during the execution of your application.

Threading

JNI does not enforce any limitations on the execution model of the native code. Both the Java code and the native code can achieve parallel processing through the use of threads. These threads can be either Java threads or platform threads, like POSIX threads. This flexibility makes it easier to reuse existing native modules as part of a Java application through JNI, as the threading model remains compatible.

Although both threading mechanisms can run simultaneously side by side, there are certain constraints of JNI to keep in mind if you expect your native, non-Java threads to access any of the JNI functions.

static JavaVM* vm = 0;

JNIEXPORT jstring JNICALL Java_com_apress_example_Unix_init(JNIEnv* env, jclass clazz) {
    if (0 != env->GetJavaVM( &vm)) {
        /* Error occured. */
    } else {
        /* JavaVM obtained. */
    }
}

void threadWorker() {
    JNIEnv* env = 0;

    if (0 = (*vm)->AttachCurrentThread(vm, &env, NULL)) {
        /* Error occurred. */
    } else {
        /* JNI API can be accessed using the JNIEnv. */
    }
}

(*vm)->DetachCurrentThread();
env = 0;

Extended JNI Check

In order to deliver high performance at runtime, the JNI functions do very little error checking. Errors usually result in a crash that is hard to troubleshoot. Dalvik VM provides an extended checking mode for JNI calls, known as CheckJNI. When it is enabled, JavaVM and JNIEnv interface pointers are switched to tables of functions that perform an extended level of error checking before calling the actual implementation. CheckJNI can detect the following problems:

• Attempt to allocate a negative-sized array
• Bad or NULL pointers passed to JNI functions’ Syntax errors while passing class names
• Making JNI calls while in critical section
• Bad arguments passed to NewDirectByeBuffer
• Making JNI calls when an exception is pending
• JNIEnv interface pointer used in wrong thread
• Field type and Set<Type>Field function mismatch
• Method type and Call<Type>Method function mismatch, such as DeleteGlobalRef/DeleteLocalRef called with wrong reference type
• Bad release mode passed to Release<Type>ArrayElement function
• Incompatible type returned from native method
• Invalid UTF-8 sequence passed to a JNI call

By default, the CheckJNI mode is enabled only in the emulator, not on the regular Android devices, because of its effect on the overall performance of the system. On a regular device, the CheckJNI mode can be enabled by issuing the following on the command prompt:

adb shell setprop debug.checkjni 1

This won’t affect the running applications, but any application launched afterwards will have CheckJNI enabled. It is a good practice to observe your application running in the CheckJNI mode to spot any problems in your native code before they lead the application into much complicated problems.

Always Check for Java Exceptions

Exception handling is an important aspect of the Java programming language. Exceptions behave differently in the JNI than they do in Java. In Java, when an exception is thrown, the virtual machine stops the execution of the code block and goes through the call stack in reverse order to find an exception handler code block that can handle the specific exception type. This is also called catching an exception. The virtual machine clears the exception and transfers the control to the exception handler block. In contrast, the JNI requires developers to explicitly implement the exception handling flow after an exception has occurred.

You can catch Java exceptions in native code using the JNI API call ExceptionOccurred. This function queries the Java VM for any pending exception, and it returns a local reference to the exception Java object, as shown in Listing 5-22.

Listing 5-22.   Catching and Handling Exceptions in Native Code

jthrowable ex;
...
env->CallVoidMethod(instance, throwingMethodId);
ex = env->ExceptionOccurred(env);
if (0 != ex) {
    env->ExceptionClear(env);

    /* Exception handler. */
}

Failure to do so will not block the execution of your native function; however, any subsequent calls to JNI API will silently fail. This can become very hard to troubleshoot, as the actual exception does not leave any traces behind.

As a good practice, you should always check whether a Java exception has been thrown after invoking any Java methods that may throw an exception.

Upon handling the exception, you should also clear it using the ExceptionClear function to inform the Java VM that the exception is handled and JNI can resume serving requests to Java space.

Always Check JNI Return Values

Exceptions are extensions of the programming language for developers to report and handle exceptional events that require special processing outside the actual flow of the application. Although exceptions have been part of the Java programming language since its very beginning, exception support is not widely available for C/C++ programming language on all platforms. Because JNI is designed to be a universal solution to facilitate integration of native modules into Java applications, it does not use exceptions. The JNI API functions instead rely on their return values to indicate any errors during the execution of the API call, as shown in Listing 5-23.

Listing 5-23.   Checking the Return Value of JNI API Calls

jclass clazz;
...
clazz = env->FindClass("java/lang/String");
if (0 == clazz) {
    /* Class could not be found. */
} else {
    /* Class is found, you can use the return value. */
}

Thus, as a good practice, never assume it is safe to use the return value of a JNI API call as is. Always check the return value to make sure the JNI API call was successfully executed and the proper usable value is returned to your native function.

Always Add Log Lines While Developing

Logging is the most important part of troubleshooting, but it is tricky to achieve, especially on mobile platforms where the development and the execution of the application happen on two different machines. As a good practice, you should always include log messages while developing your application, not when you are trying to troubleshoot a problem, as it will be too late by then. Having proper logging part of your application can help you to troubleshoot problems much easily by simply looking at the log output of your applications. Needless to say, reading and sharing log messages is much easier process than using sophisticated debugger applications to inspect the execution of an application.

Although adding logging into your application is an appealing solution, having an extensive amount of logging will impact the performance of your application, and it will also expose too much about the internal flow of your application to external parties. Although it’s good to have extensive logging during the development and troubleshooting stage, you should strip those components from your application before releasing it. Despite the vast number of logging frameworks that are available in Java space, the options are fairly limited for C/C++ code. In this section, you will fill this gap by building a small logging framework for C/C++ code.

In order to achieve the same functionality that is offered by the advanced logging frameworks, the solution that is presented in this section will be rely heavily on the preprocessor support provided by the native C/C++ compiler. The my_log.h header file that is shown in Listing 5-24 through a set of preprocessor directives, wraps the Android native logging APIs to provide a compile-time control over the intensity of logging.

Listing 5-24.   The my_log.h Logging Header File

#pragma once

/**
 * Basic logging framework for NDK.
 *
 * @author Onur Cinar
 */

#include <android/log.h>

#define MY_LOG_LEVEL_VERBOSE 1
#define MY_LOG_LEVEL_DEBUG 2
#define MY_LOG_LEVEL_INFO 3
#define MY_LOG_LEVEL_WARNING 4
#define MY_LOG_LEVEL_ERROR 5
#define MY_LOG_LEVEL_FATAL 6
#define MY_LOG_LEVEL_SILENT 7

#ifndef MY_LOG_TAG
#    define MY_LOG_TAG __FILE__
#endif

#ifndef MY_LOG_LEVEL
#    define MY_LOG_LEVEL MY_LOG_LEVEL_VERBOSE
#endif

#define MY_LOG_NOOP (void) 0

#define MY_LOG_PRINT(level,fmt,...) 
        __android_log_print(level, MY_LOG_TAG, "(%s:%u) %s: " fmt, 
                __FILE__, __LINE__, __PRETTY_FUNCTION__, ##__VA_ARGS__)

#if MY_LOG_LEVEL_VERBOSE >= MY_LOG_LEVEL
#    define MY_LOG_VERBOSE(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_VERBOSE, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_VERBOSE(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_DEBUG >= MY_LOG_LEVEL
#    define MY_LOG_DEBUG(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_DEBUG, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_DEBUG(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_INFO >= MY_LOG_LEVEL
#    define MY_LOG_INFO(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_INFO, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_INFO(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_WARNING >= MY_LOG_LEVEL
#    define MY_LOG_WARNING(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_WARN, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_WARNING(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_ERROR >= MY_LOG_LEVEL
#    define MY_LOG_ERROR(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_ERROR, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_ERROR(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_FATAL >= MY_LOG_LEVEL
#    define MY_LOG_FATAL(fmt,...) 
        MY_LOG_PRINT(ANDROID_LOG_FATAL, fmt, ##__VA_ARGS__)
#else
#    define MY_LOG_FATAL(...) MY_LOG_NOOP
#endif

#if MY_LOG_LEVEL_FATAL >= MY_LOG_LEVEL
#    define MY_LOG_ASSERT(expression, fmt, ...) 
        if (!(expression)) 
        { 
            __android_log_assert(#expression, MY_LOG_TAG, 
                fmt, ##__VA_ARGS__); 
        }
#else
#    define MY_LOG_ASSERT(...) MY_LOG_NOOP
#endif

In order to use this tiny logging framework, simply include the my_log.h header file:

#include "my_log.h"

This will make the logging macros available to the source code. You can then use them in your native code, as shown in Listing 5-25.

Listing 5-25.   Native Code with Logging Macros

...

MY_LOG_VERBOSE("The native method is called.");

MY_LOG_DEBUG("env=%p thiz=%p", env, thiz);

MY_LOG_ASSERT(0 != env, "JNIEnv cannot be NULL.");

...

The tiny logging framework still relies on the Android logging functions. As the last step, you should modify the Android.mk build file as shown in Listing 5-26.

Listing 5-26.   Setting the Log Level Through the Build Script

LOCAL_MODULE := module
...
# Define the log tag
MY_LOG_TAG := module

# Define the default logging level based build type
ifeq ($(APP_OPTIM),release)
  MY_LOG_LEVEL := MY_LOG_LEVEL_ERROR
else
  MY_LOG_LEVEL := MY_LOG_LEVEL_VERBOSE
endif

# Appending the compiler flags
LOCAL_CFLAGS += -DMY_LOG_TAG=$(MY_LOG_TAG)
LOCAL_CFLAGS += -DMY_LOG_LEVEL=$(MY_LOG_LEVEL)

LOCAL_SRC_FILES := module.c

# Dynamically linking with the log library
LOCAL_LDLIBS += -llog

You can always improve this simple logging framework based on the unique requirements of your application. Using a logging framework is a good practice, as it will enable you to control the amount of logging your application will produce, without making any modifications to the source code. Having logging available in advance can save you time while troubleshooting complicated errors in native components.