1/* Copyright 2018 The TensorFlow Authors. All Rights Reserved.
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7 http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations 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
31extern "C" {
32#endif
33
34typedef struct TF_WritableFileHandle TF_WritableFileHandle;
35typedef struct TF_StringStream TF_StringStream;
36typedef struct TF_Thread TF_Thread;
37
38typedef 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
56TF_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
61TF_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
85TF_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.
92TF_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).
99TF_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.
105TF_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.
110TF_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.
118TF_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.
123TF_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.
129TF_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.
138TF_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.
143TF_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).
148TF_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).
154TF_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.
158TF_CAPI_EXPORT extern char* TF_GetTempFileName(const char* extension);
159
160// Returns the number of nanoseconds since the Unix epoch.
161TF_CAPI_EXPORT extern uint64_t TF_NowNanos(void);
162
163// Returns the number of microseconds since the Unix epoch.
164TF_CAPI_EXPORT extern uint64_t TF_NowMicros(void);
165
166// Returns the number of seconds since the Unix epoch.
167TF_CAPI_EXPORT extern uint64_t TF_NowSeconds(void);
168
169// Populates a TF_ThreadOptions struct with system-default values.
170TF_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.
180TF_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.
186TF_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.
196TF_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.
204TF_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