1 // Copyright 2022 Google Inc. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at: 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #import <Foundation/Foundation.h> 16 17 NS_ASSUME_NONNULL_BEGIN 18 19 @class TFLTensor; 20 21 /** Domain for errors in the signature runner API. */ 22 FOUNDATION_EXPORT NSErrorDomain const TFLSignatureRunnerErrorDomain; 23 24 /** 25 * @enum TFLSignatureRunnerErrorCode 26 * This enum specifies various error codes related to `TFLSignatureRunner`. 27 */ 28 typedef NS_ENUM(NSUInteger, TFLSignatureRunnerErrorCode) { 29 /** Input data has invalid byte size. */ 30 TFLSignatureRunnerErrorCodeInvalidInputByteSize, 31 32 /** Provided shape is invalid. It must be a non-empty array of positive unsigned integers. */ 33 TFLSignatureRunnerErrorCodeInvalidShape, 34 35 /** Failed to create `TFLSignatureRunner`. */ 36 TFLSignatureRunnerErrorCodeFailedToCreateSignatureRunner, 37 38 /** Failed to invoke `TFLSignatureRunner`. */ 39 TFLSignatureRunnerErrorCodeFailedToInvoke, 40 41 /** Failed to retrieve a tensor. */ 42 TFLSignatureRunnerErrorCodeFailedToGetTensor, 43 44 /** Invalid tensor. */ 45 TFLSignatureRunnerErrorCodeInvalidTensor, 46 47 /** Failed to resize an input tensor. */ 48 TFLSignatureRunnerErrorCodeFailedToResizeInputTensor, 49 50 /** Failed to copy data into an input tensor. */ 51 TFLSignatureRunnerErrorCodeFailedToCopyDataToInputTensor, 52 53 /** Copying data into an output tensor not allowed. */ 54 TFLSignatureRunnerErrorCodeCopyDataToOutputTensorNotAllowed, 55 56 /** Failed to get data from a tensor. */ 57 TFLSignatureRunnerErrorCodeFailedToGetDataFromTensor, 58 59 /** Failed to allocate memory for tensors. */ 60 TFLSignatureRunnerErrorCodeFailedToAllocateTensors, 61 }; 62 63 /** 64 * A TensorFlow Lite model signature runner. You can get a `TFLSignatureRunner` instance for a 65 * signature from the `TFLInterpreter` and then use the SignatureRunner APIs. 66 * 67 * @note `TFLSignatureRunner` instances are *not* thread-safe. 68 * @note Each `TFLSignatureRunner` instance is associated with a `TFLInterpreter` instance. As long 69 * as a `TFLSignatureRunner` instance is still in use, its associated `TFLInterpreter` instance 70 * will not be deallocated. 71 */ 72 @interface TFLSignatureRunner : NSObject 73 74 /** The signature key. */ 75 @property(nonatomic, readonly) NSString *signatureKey; 76 77 /** An ordered list of the SignatureDefs input names. */ 78 @property(nonatomic, readonly) NSArray<NSString *> *inputs; 79 80 /** An ordered list of the SignatureDefs output names. */ 81 @property(nonatomic, readonly) NSArray<NSString *> *outputs; 82 83 - (instancetype)init NS_UNAVAILABLE; 84 + (instancetype)new NS_UNAVAILABLE; 85 86 /** 87 * Returns the input tensor with the given input name in the signature. 88 * 89 * @param name The input name in the signature. 90 * @param error An optional error parameter populated when there is an error in looking up the input 91 * tensor. 92 * 93 * @return The input tensor with the given input name. `nil` if there is an error. See the 94 * `TFLTensor` class documentation for more details on the life expectancy between the returned 95 * tensor and this signature runner. 96 */ 97 - (nullable TFLTensor *)inputTensorWithName:(NSString *)name error:(NSError **)error; 98 99 /** 100 * Returns the output tensor with the given output name in the signature. 101 * 102 * @param name The output name in the signature. 103 * @param error An optional error parameter populated when there is an error in looking up the 104 * output tensor. 105 * 106 * @return The output tensor with the given output name. `nil` if there is an error. See the 107 * `TFLTensor` class documentation for more details on the life expectancy between the returned 108 * tensor and this signature runner. 109 */ 110 - (nullable TFLTensor *)outputTensorWithName:(NSString *)name error:(NSError **)error; 111 112 /** 113 * Resizes the input tensor with the given input name to the specified shape (an array of positive 114 * unsigned integers). 115 * 116 * @param name The input name. 117 * @param shape Shape that the given input tensor should be resized to. It should be an array of 118 * positive unsigned integer(s) containing the size of each dimension. 119 * @param error An optional error parameter populated when there is an error in resizing the input 120 * tensor. 121 * 122 * @return Whether the input tensor was resized successfully. Returns NO if an error occurred. 123 */ 124 - (BOOL)resizeInputTensorWithName:(NSString *)name 125 toShape:(NSArray<NSNumber *> *)shape 126 error:(NSError **)error; 127 128 /** 129 * Allocates memory for tensors. 130 * 131 * @note This call is *purely optional*. Tensor allocation will occur automatically during 132 * execution. 133 * 134 * @param error An optional error parameter populated when there is an error in allocating memory. 135 * 136 * @return Whether memory allocation is successful. Returns NO if an error occurred. 137 */ 138 - (BOOL)allocateTensorsWithError:(NSError **)error; 139 140 /** 141 * Invoke the signature with given input data. 142 * 143 * @param inputs A map from input name to the input data. The input data will be copied into the 144 * input tensor. 145 * @param error An optional error parameter populated when there is an error in invoking the 146 * signature. 147 * 148 * @return Whether the invocation is successful. Returns NO if an error occurred. 149 */ 150 - (BOOL)invokeWithInputs:(NSDictionary<NSString *, NSData *> *)inputs Error:(NSError **)error; 151 152 @end 153 154 NS_ASSUME_NONNULL_END 155