lite/abi/tflite.h

Native functions for initializing and shutting down the TensorFlow Lite (TFLite) in Google Play Services Native API.

Summary

One of the following functions must be called (and must return successfully) before any of the TFLite C API functions are called:

  • the GmsTfLiteInitialize() or GmsTfLiteInitializeOrThrow() native functions defined in this header file.
  • the com.google.android.gms.tflite.java.TfLiteNative.initialize(Context context) or com.google.android.gms.tflite.java.TfLiteNative.initialize(Context context, TfLiteInitializationOptions options) methods defined in the Java API.

Functions
GmsTfLiteCheckInitializedOrThrow(JNIEnv *env)
bool
Checks whether the TFLite API has been initialized, throwing a Java exception otherwise.
GmsTfLiteErrorCodeVersionTooNew(int error_code)
bool
Returns true if the error code indicates the TFLite ABI version is too new.
GmsTfLiteErrorCodeVersionTooOld(int error_code)
bool
Returns true if the error code indicates that the TFLite ABI version is too old.
GmsTfLiteInitialize(JNIEnv *env, jobjecthandle)
int
Initialize TFLite with a handle acquired from Google Play Services API.
GmsTfLiteInitializeOrThrow(JNIEnv *env, jobjecthandle)
bool
Initialize TFLite with a handle acquired from Google Play Services API, throwing a Java exception on failure.
GmsTfLiteShutdown(void)
void
Resets the TFLite API.

Functions

GmsTfLiteCheckInitializedOrThrow

bool GmsTfLiteCheckInitializedOrThrow(
  JNIEnv *env
)

Checks whether the TFLite API has been initialized, throwing a Java exception otherwise.

Details
Parameters
env
The JNIEnv for the current thread (which has to be attached to the JVM).
Returns
Whether or not the TFLite API has been initialized. If this method returns false, no other JNI method should be called until the pending exception has been handled (typically by returning to Java).

GmsTfLiteErrorCodeVersionTooNew

bool GmsTfLiteErrorCodeVersionTooNew(
  int error_code
)

Returns true if the error code indicates the TFLite ABI version is too new.

In this case, the client should be updated to a newer version.

To avoid this error, make sure that your app is built against the latest version of the TFLite in Google Play Services client library code.

If TFLite is important for the functionality of the app, then we recommend that the calling code notify the user in this case. Suggested actions for the user could include:

  • Try updating the app to the latest version

If the in-app update API (https://developer.android.com/guide/playcore/in-app-updates) is available, we also recommend using the in-app update API to allow the user to automatically update the app if a new version is available.

Details
Parameters
error_code
An error code returned by GmsTfLiteInitialize.

GmsTfLiteErrorCodeVersionTooOld

bool GmsTfLiteErrorCodeVersionTooOld(
  int error_code
)

Returns true if the error code indicates that the TFLite ABI version is too old.

In this case, the TFLite in Google Play Services module should be updated to a newer version.

If TFLite is important for the functionality of the app, then we recommend that the calling code notify the user in this case. Suggested actions for the user could include:

Details
Parameters
error_code
An error code returned by GmsTfLiteInitialize.

GmsTfLiteInitialize

int GmsTfLiteInitialize(
  JNIEnv *env,
  jobjecthandle
)

Initialize TFLite with a handle acquired from Google Play Services API.

This method (along with GmsTfLiteInitializeOrThrow()) can be called multiple times with the same handle; attempting to initialize with a different handle (without a call to GmsTfLiteShutdown() in between) will fail.

Details
Parameters
env
The JNIEnv for the current thread (which has to be attached to the JVM).
handle
An InternalNativeInitializationHandle object acquired through the Google Play Services API.
Returns
0 on success, or a non-zero error code on failure. The error codes are implementation-specific, but error conditions that clients may need to deal with can be tested using the GmsTfLiteErrorCodeVersionTooOld() and GmsTfLiteErrorCodeVersionTooNew() functions. Clients may also wish to log the specific error code for ease of debugging.

GmsTfLiteInitializeOrThrow

bool GmsTfLiteInitializeOrThrow(
  JNIEnv *env,
  jobjecthandle
)

Initialize TFLite with a handle acquired from Google Play Services API, throwing a Java exception on failure.

This method (along with GmsTfLiteInitialize()) can be called multiple times with the same handle; attempting to initialize with a different handle (without a call to GmsTfLiteShutdown() in between) will fail.

Details
Parameters
env
The JNIEnv for the current thread (which has to be attached to the JVM).
handle
An InternalNativeInitializationHandle object acquired through the Google Play Services API.
Returns
Whether or not initialization was successful. If this method returns false, no other JNI method should be called until the pending exception has been handled (typically by returning to Java).

GmsTfLiteShutdown

void GmsTfLiteShutdown(
  void
)

Resets the TFLite API.

After this method is called, the TFLite API will be unusable until a subsequent call to GmsTfLiteInitialize() or GmsTfLiteInitializeOrThrow(). This can be used to switch to a different version of the TFLite library.