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