1 /* Copyright 2018 The TensorFlow Authors. 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 16 #ifndef TENSORFLOW_C_ENV_H_ 17 #define TENSORFLOW_C_ENV_H_ 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #include "tensorflow/c/c_api_macros.h" 24 #include "tensorflow/c/tf_file_statistics.h" 25 #include "tensorflow/c/tf_status.h" 26 27 // -------------------------------------------------------------------------- 28 // C API for tensorflow::Env. 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 typedef struct TF_WritableFileHandle TF_WritableFileHandle; 35 typedef struct TF_StringStream TF_StringStream; 36 typedef struct TF_Thread TF_Thread; 37 38 typedef struct TF_ThreadOptions { 39 // Thread stack size to use (in bytes), zero implies that the system default 40 // will be used. 41 size_t stack_size; 42 43 // Guard area size to use near thread stacks to use (in bytes), zero implies 44 // that the system default will be used. 45 size_t guard_size; 46 47 // The NUMA node to use, -1 implies that there should be no NUMA affinity for 48 // this thread. 49 int numa_node; 50 } TF_ThreadOptions; 51 52 // Creates the specified directory. Typical status code are: 53 // * TF_OK - successfully created the directory 54 // * TF_ALREADY_EXISTS - directory already exists 55 // * TF_PERMISSION_DENIED - dirname is not writable 56 TF_CAPI_EXPORT extern void TF_CreateDir(const char* dirname, TF_Status* status); 57 58 // Deletes the specified directory. Typical status codes are: 59 // * TF_OK - successfully deleted the directory 60 // * TF_FAILED_PRECONDITION - the directory is not empty 61 TF_CAPI_EXPORT extern void TF_DeleteDir(const char* dirname, TF_Status* status); 62 63 // Deletes the specified directory and all subdirectories and files underneath 64 // it. This is accomplished by traversing the directory tree rooted at dirname 65 // and deleting entries as they are encountered. 66 // 67 // If dirname itself is not readable or does not exist, *undeleted_dir_count is 68 // set to 1, *undeleted_file_count is set to 0 and an appropriate status (e.g. 69 // TF_NOT_FOUND) is returned. 70 // 71 // If dirname and all its descendants were successfully deleted, TF_OK is 72 // returned and both error counters are set to zero. 73 // 74 // Otherwise, while traversing the tree, undeleted_file_count and 75 // undeleted_dir_count are updated if an entry of the corresponding type could 76 // not be deleted. The returned error status represents the reason that any one 77 // of these entries could not be deleted. 78 // 79 // Typical status codes: 80 // * TF_OK - dirname exists and we were able to delete everything underneath 81 // * TF_NOT_FOUND - dirname doesn't exist 82 // * TF_PERMISSION_DENIED - dirname or some descendant is not writable 83 // * TF_UNIMPLEMENTED - some underlying functions (like Delete) are not 84 // implemented 85 TF_CAPI_EXPORT extern void TF_DeleteRecursively(const char* dirname, 86 int64_t* undeleted_file_count, 87 int64_t* undeleted_dir_count, 88 TF_Status* status); 89 90 // Obtains statistics for the given path. If status is TF_OK, *stats is 91 // updated, otherwise it is not touched. 92 TF_CAPI_EXPORT extern void TF_FileStat(const char* filename, 93 TF_FileStatistics* stats, 94 TF_Status* status); 95 96 // Creates or truncates the given filename and returns a handle to be used for 97 // appending data to the file. If status is TF_OK, *handle is updated and the 98 // caller is responsible for freeing it (see TF_CloseWritableFile). 99 TF_CAPI_EXPORT extern void TF_NewWritableFile(const char* filename, 100 TF_WritableFileHandle** handle, 101 TF_Status* status); 102 103 // Closes the given handle and frees its memory. If there was a problem closing 104 // the file, it is indicated by status. Memory is freed in any case. 105 TF_CAPI_EXPORT extern void TF_CloseWritableFile(TF_WritableFileHandle* handle, 106 TF_Status* status); 107 108 // Syncs content of the handle to the filesystem. Blocks waiting for the 109 // filesystem to indicate that the content has been persisted. 110 TF_CAPI_EXPORT extern void TF_SyncWritableFile(TF_WritableFileHandle* handle, 111 TF_Status* status); 112 113 // Flush local buffers to the filesystem. If the process terminates after a 114 // successful flush, the contents may still be persisted, since the underlying 115 // filesystem may eventually flush the contents. If the OS or machine crashes 116 // after a successful flush, the contents may or may not be persisted, depending 117 // on the implementation. 118 TF_CAPI_EXPORT extern void TF_FlushWritableFile(TF_WritableFileHandle* handle, 119 TF_Status* status); 120 121 // Appends the given bytes to the file. Any failure to do so is indicated in 122 // status. 123 TF_CAPI_EXPORT extern void TF_AppendWritableFile(TF_WritableFileHandle* handle, 124 const char* data, 125 size_t length, 126 TF_Status* status); 127 128 // Deletes the named file and indicates whether successful in *status. 129 TF_CAPI_EXPORT extern void TF_DeleteFile(const char* filename, 130 TF_Status* status); 131 132 // Retrieves the next item from the given TF_StringStream and places a pointer 133 // to it in *result. If no more items are in the list, *result is set to NULL 134 // and false is returned. 135 // 136 // Ownership of the items retrieved with this function remains with the library. 137 // Item points are invalidated after a call to TF_StringStreamDone. 138 TF_CAPI_EXPORT extern bool TF_StringStreamNext(TF_StringStream* list, 139 const char** result); 140 141 // Frees the resources associated with given string list. All pointers returned 142 // by TF_StringStreamNext are invalid after this call. 143 TF_CAPI_EXPORT extern void TF_StringStreamDone(TF_StringStream* list); 144 145 // Retrieves the list of children of the given directory. You can iterate 146 // through the list with TF_StringStreamNext. The caller is responsible for 147 // freeing the list (see TF_StringStreamDone). 148 TF_CAPI_EXPORT extern TF_StringStream* TF_GetChildren(const char* filename, 149 TF_Status* status); 150 151 // Retrieves a list of directory names on the local machine that may be used for 152 // temporary storage. You can iterate through the list with TF_StringStreamNext. 153 // The caller is responsible for freeing the list (see TF_StringStreamDone). 154 TF_CAPI_EXPORT extern TF_StringStream* TF_GetLocalTempDirectories(void); 155 156 // Creates a temporary file name with an extension. 157 // The caller is responsible for freeing the returned pointer. 158 TF_CAPI_EXPORT extern char* TF_GetTempFileName(const char* extension); 159 160 // Returns the number of nanoseconds since the Unix epoch. 161 TF_CAPI_EXPORT extern uint64_t TF_NowNanos(void); 162 163 // Returns the number of microseconds since the Unix epoch. 164 TF_CAPI_EXPORT extern uint64_t TF_NowMicros(void); 165 166 // Returns the number of seconds since the Unix epoch. 167 TF_CAPI_EXPORT extern uint64_t TF_NowSeconds(void); 168 169 // Populates a TF_ThreadOptions struct with system-default values. 170 TF_CAPI_EXPORT extern void TF_DefaultThreadOptions(TF_ThreadOptions* options); 171 172 // Returns a new thread that is running work_func and is identified 173 // (for debugging/performance-analysis) by thread_name. 174 // 175 // The given param (which may be null) is passed to work_func when the thread 176 // starts. In this way, data may be passed from the thread back to the caller. 177 // 178 // Caller takes ownership of the result and must call TF_JoinThread on it 179 // eventually. 180 TF_CAPI_EXPORT extern TF_Thread* TF_StartThread(const TF_ThreadOptions* options, 181 const char* thread_name, 182 void (*work_func)(void*), 183 void* param); 184 185 // Waits for the given thread to finish execution, then deletes it. 186 TF_CAPI_EXPORT extern void TF_JoinThread(TF_Thread* thread); 187 188 // \brief Load a dynamic library. 189 // 190 // Pass "library_filename" to a platform-specific mechanism for dynamically 191 // loading a library. The rules for determining the exact location of the 192 // library are platform-specific and are not documented here. 193 // 194 // On success, place OK in status and return the newly created library handle. 195 // Otherwise returns nullptr and set error status. 196 TF_CAPI_EXPORT extern void* TF_LoadSharedLibrary(const char* library_filename, 197 TF_Status* status); 198 199 // \brief Get a pointer to a symbol from a dynamic library. 200 // 201 // "handle" should be a pointer returned from a previous call to 202 // TF_LoadLibraryFromEnv. On success, place OK in status and return a pointer to 203 // the located symbol. Otherwise returns nullptr and set error status. 204 TF_CAPI_EXPORT extern void* TF_GetSymbolFromLibrary(void* handle, 205 const char* symbol_name, 206 TF_Status* status); 207 208 #ifdef __cplusplus 209 } 210 #endif 211 212 #endif // TENSORFLOW_C_ENV_H_ 213