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 | |