Implementation:Microsoft Onnxruntime OrtSession SessionOptions JNI

Knowledge Sources	Description
Source File	java/src/main/native/ai_onnxruntime_OrtSession_SessionOptions.c
Repository	Microsoft/onnxruntime

Domains

• JNI Native Bridge
• Session Configuration
• Execution Provider Registration

Overview

ai_onnxruntime_OrtSession_SessionOptions.c is the JNI native implementation file for the OrtSession.SessionOptions Java inner class. It provides native methods for creating and configuring session options including execution mode, optimization level, threading, profiling, memory patterns, logging, custom operator libraries, dimension overrides, initializers, and registering execution providers (CPU, CUDA, DNNL, OpenVINO, TensorRT, NNAPI, TVM, CoreML, ROCM, DirectML, ACL, ArmNN, MIGraphX, and generic string-configured providers).

Description

Key function groups:

• Options lifecycle: createOptions creates a new OrtSessionOptions with inter-op threads set to 1 and optionally enables extension custom ops. closeOptions releases the options.
• Execution configuration: setExecutionMode (sequential/parallel), setOptimizationLevel (none/basic/extended/all), setIntraOpNumThreads, setInterOpNumThreads, disablePerSessionThreads, setDeterministicCompute.
• Model optimization: setOptimizationModelFilePath sets the path for saving the optimized model (with Win32 wide-char support).
• Profiling: enableProfiling and disableProfiling with platform-specific path handling.
• Memory: setMemoryPatternOptimization toggles memory pattern optimization. setCPUArenaAllocator enables/disables the CPU memory arena.
• Logging: setSessionLogLevel, setSessionLogVerbosityLevel, setLoggerId.
• Custom operators: registerCustomOpLibrary loads a shared library and returns its handle. registerCustomOpsUsingFunction registers ops via a named function. closeCustomLibraries unloads libraries (FreeLibrary on Win32, dlclose on Unix).
• Initializers: addInitializer adds a single named initializer. addExternalInitializers adds multiple named initializers in batch. addFreeDimensionOverrideByName overrides a free dimension.
• Config entries: addConfigEntry adds a key-value configuration string.
• Execution providers (legacy): addCPU, addCUDA, addCUDAV2, addDnnl, addOpenVINO, addTensorrt, addTensorrtV2, addNnapi, addTvm, addCoreML, addROCM, addDirectML, addACL, addArmNN, addMIGraphX. Each is conditionally compiled with #ifdef USE_* guards; unsupported providers throw OrtException.
• Generic EP registration: Two overloaded addExecutionProvider methods: (1) string-based with EP name and key-value config arrays via SessionOptionsAppendExecutionProvider; (2) device-based with OrtEpDevice handles, env, and key-value config via SessionOptionsAppendExecutionProvider_V2.

Code Reference

Source Location

// File: java/src/main/native/ai_onnxruntime_OrtSession_SessionOptions.c

Signature

// Options lifecycle
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_createOptions(JNIEnv*, jobject, jlong);
JNIEXPORT void  JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_closeOptions(JNIEnv*, jobject, jlong, jlong);

// Execution configuration
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setExecutionMode(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setOptimizationLevel(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setIntraOpNumThreads(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setInterOpNumThreads(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_disablePerSessionThreads(JNIEnv*, jobject, jlong, jlong);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setDeterministicCompute(JNIEnv*, jobject, jlong, jlong, jboolean);

// Profiling
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_enableProfiling(JNIEnv*, jobject, jlong, jlong, jstring);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_disableProfiling(JNIEnv*, jobject, jlong, jlong);

// Memory and logging
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setMemoryPatternOptimization(JNIEnv*, jobject, jlong, jlong, jboolean);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setCPUArenaAllocator(JNIEnv*, jobject, jlong, jlong, jboolean);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setSessionLogLevel(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setSessionLogVerbosityLevel(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_setLoggerId(JNIEnv*, jobject, jlong, jlong, jstring);

// Custom operators
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_registerCustomOpLibrary(JNIEnv*, jobject, jlong, jlong, jstring);
JNIEXPORT void  JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_registerCustomOpsUsingFunction(JNIEnv*, jobject, jlong, jlong, jstring);
JNIEXPORT void  JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_closeCustomLibraries(JNIEnv*, jobject, jlongArray);

// Execution providers (subset shown)
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addCPU(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addCUDA(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addCUDAV2(JNIEnv*, jobject, jlong, jlong, jlong);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addTensorrt(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addTensorrtV2(JNIEnv*, jobject, jlong, jlong, jlong);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addCoreML(JNIEnv*, jobject, jlong, jlong, jint);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addNnapi(JNIEnv*, jobject, jlong, jlong, jint);

// Generic EP registration (2 overloads)
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addExecutionProvider__JJLjava_lang_String_2_3Ljava_lang_String_2_3Ljava_lang_String_2
    (JNIEnv*, jobject, jlong, jlong, jstring, jobjectArray, jobjectArray);
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_00024SessionOptions_addExecutionProvider__JJJ_3J_3Ljava_lang_String_2_3Ljava_lang_String_2
    (JNIEnv*, jobject, jlong, jlong, jlong, jlongArray, jobjectArray, jobjectArray);

Import

#include "OrtJniUtil.h"
#include "ai_onnxruntime_OrtSession_SessionOptions.h"
// Provider factory headers (conditionally compiled)
#include "onnxruntime/core/providers/cpu/cpu_provider_factory.h"
#include "onnxruntime/core/providers/nnapi/nnapi_provider_factory.h"
#include "onnxruntime/core/providers/coreml/coreml_provider_factory.h"
// ... and others based on USE_* compile flags

I/O Contract

Inputs

Name	Type	Description
apiHandle	jlong	Pointer to the ORT C API struct
optionsHandle	jlong	Pointer to the native OrtSessionOptions
envHandle	jlong	Pointer to OrtEnv (for V2 EP registration)
mode	jint	Execution mode (sequential=0, parallel=1)
optLevel	jint	Optimization level (none=0, basic=1, extended=2, all=99)
numThreads	jint	Thread count for intra-op or inter-op parallelism
deviceID	jint	GPU device index for provider registration
libraryPath	jstring	Path to custom operator shared library
epName	jstring	Execution provider name for generic registration
configKeyArr	jobjectArray	String array of configuration keys
configValueArr	jobjectArray	String array of configuration values
deviceHandleArr	jlongArray	Array of OrtEpDevice native handles (V2 registration)

Outputs

Name	Type	Description
optionsHandle	jlong	Pointer to the newly created OrtSessionOptions
libraryHandle	jlong	Handle to the loaded custom operator library

Usage Examples

// Inside JNI: create session options and configure
jlong opts = Java_ai_onnxruntime_OrtSession_00024SessionOptions_createOptions(
    jniEnv, optionsObj, apiHandle);

// Set optimization level to ALL
Java_ai_onnxruntime_OrtSession_00024SessionOptions_setOptimizationLevel(
    jniEnv, optionsObj, apiHandle, opts, 99);

// Add CUDA execution provider on device 0
Java_ai_onnxruntime_OrtSession_00024SessionOptions_addCUDA(
    jniEnv, optionsObj, apiHandle, opts, 0);

// Add a generic execution provider with config
Java_ai_onnxruntime_OrtSession_00024SessionOptions_addExecutionProvider__JJLjava_lang_String_2_3Ljava_lang_String_2_3Ljava_lang_String_2(
    jniEnv, optionsObj, apiHandle, opts, epNameStr, keysArr, valsArr);

// Release options
Java_ai_onnxruntime_OrtSession_00024SessionOptions_closeOptions(
    jniEnv, optionsObj, apiHandle, opts);

Related Pages

• OrtSession.java - Java-side SessionOptions inner class calling these natives
• ai_onnxruntime_OrtSession.c - OrtSession JNI implementation (session creation, run)
• OrtJniUtil.c - Shared utility functions (checkOrtStatus, convertExecutionMode, convertOptimizationLevel)
• OrtCUDAProviderOptions.java - Options passed to addCUDAV2
• OrtTensorRTProviderOptions.java - Options passed to addTensorrtV2