ORTSessionOptions

Objective-C

@interface ORTSessionOptions : NSObject

Swift

class ORTSessionOptions : NSObject

Options for configuring a session.

-init
Unavailable
Declaration
Objective-C

- (instancetype)init NS_UNAVAILABLE;


                    
                    
                    -initWithError:

Creates session configuration options.

Declaration

Objective-C

- (nullable instancetype)initWithError:(NSError *_Nullable *_Nullable)error;

Swift

init() throws

Parameters


                                error

Optional error information set if an error occurs.

Return Value

The instance, or nil if an error occurs.


                    
                    
                    -appendExecutionProvider:providerOptions:error:

Appends an execution provider to the session options to enable the execution provider to be used when running the model.

Available since 1.14.

The execution provider list is ordered by decreasing priority. i.e. the first provider registered has the highest priority.

Declaration

Objective-C

- (BOOL)appendExecutionProvider:(nonnull NSString *)providerName
                providerOptions:(nonnull NSDictionary<NSString *, NSString *> *)
                                    providerOptions
                          error:(NSError *_Nullable *_Nullable)error;

Swift

func appendExecutionProvider(_ providerName: String, providerOptions: [String : String] = [:]) throws

Parameters

`providerName`	Provider name. For example, “xnnpack”.
`providerOptions`	Provider-specific options. For example, for provider “xnnpack”, {“intra_op_num_threads”: “2”}.
`error`	Optional error information set if an error occurs.

Return Value

Whether the execution provider was appended successfully


                    
                    
                    -setIntraOpNumThreads:error:

Sets the number of threads used to parallelize the execution within nodes. A value of 0 means ORT will pick a default value.

Declaration

Objective-C

- (BOOL)setIntraOpNumThreads:(int)intraOpNumThreads
                       error:(NSError *_Nullable *_Nullable)error;

Swift

func setIntraOpNumThreads(_ intraOpNumThreads: Int32) throws

Parameters

`intraOpNumThreads`	The number of threads.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -setGraphOptimizationLevel:error:

Sets the graph optimization level.

Declaration

Objective-C

- (BOOL)setGraphOptimizationLevel:
            (ORTGraphOptimizationLevel)graphOptimizationLevel
                            error:(NSError *_Nullable *_Nullable)error;

Swift

func setGraphOptimizationLevel(_ graphOptimizationLevel: ORTGraphOptimizationLevel) throws

Parameters

`graphOptimizationLevel`	The graph optimization level.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -setOptimizedModelFilePath:error:

Sets the path to which the optimized model file will be saved.

Declaration

Objective-C

- (BOOL)setOptimizedModelFilePath:(nonnull NSString *)optimizedModelFilePath
                            error:(NSError *_Nullable *_Nullable)error;

Swift

func setOptimizedModelFilePath(_ optimizedModelFilePath: String) throws

Parameters

`optimizedModelFilePath`	The optimized model file path.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -setLogID:error:

Sets the session log ID.

Declaration

Objective-C

- (BOOL)setLogID:(nonnull NSString *)logID
           error:(NSError *_Nullable *_Nullable)error;

Swift

func setLogID(_ logID: String) throws

Parameters

`logID`	The log ID.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -setLogSeverityLevel:error:

Sets the session log severity level.

Declaration

Objective-C

- (BOOL)setLogSeverityLevel:(ORTLoggingLevel)loggingLevel
                      error:(NSError *_Nullable *_Nullable)error;

Swift

func setLogSeverityLevel(_ loggingLevel: ORTLoggingLevel) throws

Parameters

`loggingLevel`	The log severity level.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -addConfigEntryWithKey:value:error:

Sets a session configuration key-value pair. Any value for a previously set key will be overwritten. The session configuration keys and values are documented here: https://github.com/microsoft/onnxruntime/blob/main/include/onnxruntime/core/session/onnxruntime_session_options_config_keys.h

Declaration

Objective-C

- (BOOL)addConfigEntryWithKey:(nonnull NSString *)key
                        value:(nonnull NSString *)value
                        error:(NSError *_Nullable *_Nullable)error;

Swift

func addConfigEntry(withKey key: String, value: String) throws

Parameters

`key`	The key.
`value`	The value.
`error`	Optional error information set if an error occurs.

Return Value

Whether the option was set successfully.


                    
                    
                    -setEpContextDataReadBlock:maxDataSize:error:

Registers a block that supplies application-managed external EPContext data during session initialization.

Available since 1.31.

The block is copied and retained by these options. Each ORTSession or ORTTrainingSession created from the options takes its own strong registration snapshot for the session lifetime, so replacing or clearing the block only affects future sessions. ONNX Runtime may invoke the block concurrently from arbitrary threads; the block and any captured state must be thread-safe. The returned bytes are copied before the block’s returned NSData is released.

Return zero-length NSData for a successful empty payload. Return nil only on failure and set the provided error. Returning nil without an error produces an ONNX Runtime failure status. Data larger than maxDataSize is rejected before the native output buffer is allocated. This limit is retained and enforced by the Objective-C callback registration, not configured in the native API. It does not constrain allocations made inside the block.

The Objective-C API exposes only the application-side read callback. It does not currently expose model compilation, so the EPContext data write callback is not applicable.

Declaration

Objective-C

- (BOOL)setEpContextDataReadBlock:(nonnull ORTEpContextDataReadBlock)block
                      maxDataSize:(NSUInteger)maxDataSize
                            error:(NSError *_Nullable *_Nullable)error;

Swift

func setEpContextDataRead(_ block: @escaping ORTEpContextDataReadBlock, maxDataSize: UInt) throws

Parameters

`block`	The synchronous block used to read EPContext data.
`maxDataSize`	A finite maximum payload size in bytes. Must be greater than zero and less than `NSUIntegerMax`.
`error`	Optional error information set if registration fails.

Return Value

Whether the block was registered successfully.


                    
                    
                    -clearEpContextDataReadBlockWithError:

Clears the block that supplies application-managed external EPContext data for future sessions.

Available since 1.31.

ORTSession and ORTTrainingSession instances already created from these options retain their registration snapshot for the session lifetime.

Declaration

Objective-C

- (BOOL)clearEpContextDataReadBlockWithError:
    (NSError *_Nullable *_Nullable)error;

Swift

func clearEpContextDataReadBlock() throws

Parameters


                                error

Optional error information set if clearing fails.

Return Value

Whether the block was cleared successfully.


                    
                    
                    -registerCustomOpsUsingFunction:error:

Registers custom ops for use with ORTSessions using this SessionOptions by calling the specified native function name. The custom ops library must either be linked against, or have previously been loaded by the user.

Available since 1.14.

The registration function must have the signature: OrtStatus* (*fn)(OrtSessionOptions* options, const OrtApiBase* api);

The signature is defined in the ONNX Runtime C API: https://github.com/microsoft/onnxruntime/blob/67f4cd54fab321d83e4a75a40efeee95a6a17079/include/onnxruntime/core/session/onnxruntime_c_api.h#L697

See https://onnxruntime.ai/docs/reference/operators/add-custom-op.html for more information on custom ops. See https://github.com/microsoft/onnxruntime/blob/342a5bf2b756d1a1fc6fdc582cfeac15182632fe/onnxruntime/test/testdata/custom_op_library/custom_op_library.cc#L115 for an example of a custom op library registration function.

Note

The caller must ensure that registrationFuncName names a valid function that is visible to the native ONNX Runtime code and has the correct signature. They must ensure that the function does what they expect it to do because this method will just call it.

Declaration

Objective-C

- (BOOL)registerCustomOpsUsingFunction:(nonnull NSString *)registrationFuncName
                                 error:(NSError *_Nullable *_Nullable)error;

Swift

func registerCustomOps(usingFunction registrationFuncName: String) throws

Parameters

`registrationFuncName`	The name of the registration function to call.
`error`	Optional error information set if an error occurs.

Return Value

Whether the registration function was successfully called.


                    
                    
                    -registerCustomOpsUsingFunctionPointer:error:

Registers custom ops for use with ORTSessions using this SessionOptions by calling the specified function pointed to by registerCustomOpsFn.

Available since 1.16.

The registration function must have the signature: OrtStatus* (*fn)(OrtSessionOptions* options, const OrtApiBase* api);

The signature is defined in the ONNX Runtime C API: https://github.com/microsoft/onnxruntime/blob/67f4cd54fab321d83e4a75a40efeee95a6a17079/include/onnxruntime/core/session/onnxruntime_c_api.h#L697

Note

The caller must ensure that registerCustomOpsFn is a valid function pointer and has the correct signature. They must ensure that the function does what they expect it to do because this method will just call it.

Declaration

Objective-C

- (BOOL)registerCustomOpsUsingFunctionPointer:
            (nonnull ORTCAPIRegisterCustomOpsFnPtr)registerCustomOpsFn
                                        error:(NSError *_Nullable *_Nullable)
                                                  error;

Swift

func registerCustomOps(functionPointer registerCustomOpsFn: ORTCAPIRegisterCustomOpsFnPtr) throws

Parameters

`registerCustomOpsFn`	A pointer to the registration function to call.
`error`	Optional error information set if an error occurs.

Return Value

Whether the registration function was successfully called.


                    
                    
                    -enableOrtExtensionsCustomOpsWithError:

Registers ONNX Runtime Extensions custom ops that have been built in to ONNX Runtime.

Available since 1.16.

Note

ONNX Runtime must have been built with the --use_extensions flag for the ONNX Runtime Extensions custom ops to be able to be registered with this method. When using a separate ONNX Runtime Extensions library, use registerCustomOpsUsingFunctionPointer:error: instead.

Declaration

Objective-C

- (BOOL)enableOrtExtensionsCustomOpsWithError:
    (NSError *_Nullable *_Nullable)error;

Swift

func enableOrtExtensionsCustomOps() throws

Parameters


                                error

Optional error information set if an error occurs.

Return Value

Whether the ONNX Runtime Extensions custom ops were successfully registered.

ORTSessionOptionsCoreMLEP


                    
                    
                    -appendCoreMLExecutionProviderWithOptions:error:

Enables the CoreML execution provider in the session configuration options. It is appended to the execution provider list which is ordered by decreasing priority.

Declaration

Objective-C

- (BOOL)appendCoreMLExecutionProviderWithOptions:
            (nonnull ORTCoreMLExecutionProviderOptions *)options
                                           error:(NSError *_Nullable *_Nullable)
                                                     error;

Swift

func appendCoreMLExecutionProvider(with options: ORTCoreMLExecutionProviderOptions) throws

Parameters

`options`	The CoreML execution provider configuration options.
`error`	Optional error information set if an error occurs.

Return Value

Whether the provider was enabled successfully.


                    
                    
                    -appendCoreMLExecutionProviderWithOptionsV2:error:

Enables the CoreML execution provider in the session configuration options. It is appended to the execution provider list which is ordered by decreasing priority.

Declaration

Objective-C

- (BOOL)appendCoreMLExecutionProviderWithOptionsV2:
            (nonnull NSDictionary *)provider_options
                                             error:
                                                 (NSError *_Nullable *_Nullable)
                                                     error;

Swift

func appendCoreMLExecutionProvider(withOptionsV2 provider_options: [AnyHashable : Any] = [:]) throws

Parameters


                                provider_options

The CoreML execution provider options in dict. available keys-values: more detail in core/providers/coreml/coreml_execution_provider.h kCoremlProviderOption_MLComputeUnits: one of “CPUAndNeuralEngine”, “CPUAndGPU”, “CPUOnly”, “All” kCoremlProviderOption_ModelFormat: one of “MLProgram”, “NeuralNetwork” kCoremlProviderOption_RequireStaticInputShapes: “1” or “0” kCoremlProviderOption_EnableOnSubgraphs: “1” or “0”


                                error

Optional error information set if an error occurs.

Return Value

Whether the provider was enabled successfully.

ORTSessionOptionsXnnpackEP


                    
                    
                    -appendXnnpackExecutionProviderWithOptions:error:

Available since 1.14. Enables the Xnnpack execution provider in the session configuration options. It is appended to the execution provider list which is ordered by decreasing priority.

Declaration

Objective-C

- (BOOL)appendXnnpackExecutionProviderWithOptions:
            (nonnull ORTXnnpackExecutionProviderOptions *)options
                                            error:
                                                (NSError *_Nullable *_Nullable)
                                                    error;

Swift

func appendXnnpackExecutionProvider(with options: ORTXnnpackExecutionProviderOptions) throws

Parameters

`options`	The Xnnpack execution provider configuration options.
`error`	Optional error information set if an error occurs.

Return Value

Whether the provider was enabled successfully.