C API: Rename TF_Session to TF_DeprecatedSession.

This is one step towards having a stable C API by the time we get to TensorFlow
1.0.  A follow-up step will involve renaming TF_SessionWithGraph to TF_Session.

We want to encourage all client languages to use TF_SessionRun,
TF_GraphImportGraphDef etc. (instead of TF_Run and TF_ExtendGraph), hence
the choice of names. Ideally, all client languages will use these
functions, but it is likely that Python will continue to use
TF_DeprecatedSession for a while.
Change: 138454433
This commit is contained in:
Asim Shankar 2016-11-07 16:18:59 -08:00 committed by TensorFlower Gardener
parent fd05b5ebc5
commit fdd94f24e9
8 changed files with 81 additions and 75 deletions

View File

@ -8,6 +8,8 @@ BUS_ANY was used.
* `Env::FileExists` and `FileSystem::FileExists` now return a tensorflow::Status * `Env::FileExists` and `FileSystem::FileExists` now return a tensorflow::Status
intead of a bool. Any callers to this function can be converted to a bool intead of a bool. Any callers to this function can be converted to a bool
by adding .ok() to the call. by adding .ok() to the call.
* The C API type `TF_Session` has been renamed to `TF_DeprecatedSession`.
Please use `TF_SessionWithGraph` instead.
# Release 0.11.0 # Release 0.11.0

View File

@ -253,33 +253,34 @@ void TF_DeleteBuffer(TF_Buffer* buffer) {
TF_Buffer TF_GetBuffer(TF_Buffer* buffer) { return *buffer; } TF_Buffer TF_GetBuffer(TF_Buffer* buffer) { return *buffer; }
// -------------------------------------------------------------------------- // --------------------------------------------------------------------------
struct TF_Session { struct TF_DeprecatedSession {
Session* session; Session* session;
}; };
TF_Session* TF_NewSession(const TF_SessionOptions* opt, TF_Status* status) { TF_DeprecatedSession* TF_NewDeprecatedSession(const TF_SessionOptions* opt,
TF_Status* status) {
Session* session; Session* session;
status->status = NewSession(opt->options, &session); status->status = NewSession(opt->options, &session);
if (status->status.ok()) { if (status->status.ok()) {
return new TF_Session({session}); return new TF_DeprecatedSession({session});
} else { } else {
DCHECK_EQ(nullptr, session); DCHECK_EQ(nullptr, session);
return NULL; return NULL;
} }
} }
void TF_CloseSession(TF_Session* s, TF_Status* status) { void TF_CloseDeprecatedSession(TF_DeprecatedSession* s, TF_Status* status) {
status->status = s->session->Close(); status->status = s->session->Close();
} }
void TF_DeleteSession(TF_Session* s, TF_Status* status) { void TF_DeleteDeprecatedSession(TF_DeprecatedSession* s, TF_Status* status) {
status->status = Status::OK(); status->status = Status::OK();
delete s->session; delete s->session;
delete s; delete s;
} }
void TF_ExtendGraph(TF_Session* s, const void* proto, size_t proto_len, void TF_ExtendGraph(TF_DeprecatedSession* s, const void* proto,
TF_Status* status) { size_t proto_len, TF_Status* status) {
GraphDef g; GraphDef g;
if (!tensorflow::ParseProtoUnlimited(&g, proto, proto_len)) { if (!tensorflow::ParseProtoUnlimited(&g, proto, proto_len)) {
status->status = InvalidArgument("Invalid GraphDef"); status->status = InvalidArgument("Invalid GraphDef");
@ -531,7 +532,7 @@ static void TF_Run_Helper(
extern "C" { extern "C" {
void TF_Run(TF_Session* s, const TF_Buffer* run_options, void TF_Run(TF_DeprecatedSession* s, const TF_Buffer* run_options,
// Input tensors // Input tensors
const char** c_input_names, TF_Tensor** c_inputs, int ninputs, const char** c_input_names, TF_Tensor** c_inputs, int ninputs,
// Output tensors // Output tensors
@ -557,7 +558,7 @@ void TF_Run(TF_Session* s, const TF_Buffer* run_options,
c_outputs, target_oper_names, run_metadata, status); c_outputs, target_oper_names, run_metadata, status);
} }
void TF_PRunSetup(TF_Session* s, void TF_PRunSetup(TF_DeprecatedSession* s,
// Input names // Input names
const char** c_input_names, int ninputs, const char** c_input_names, int ninputs,
// Output names // Output names
@ -592,7 +593,7 @@ void TF_PRunSetup(TF_Session* s,
} }
} }
void TF_PRun(TF_Session* s, const char* handle, void TF_PRun(TF_DeprecatedSession* s, const char* handle,
// Input tensors // Input tensors
const char** c_input_names, TF_Tensor** c_inputs, int ninputs, const char** c_input_names, TF_Tensor** c_inputs, int ninputs,
// Output tensors // Output tensors

View File

@ -784,7 +784,7 @@ extern void TF_OperationToNodeDef(TF_Operation* oper,
// The new session API that uses TF_Graph*. The intent is this will // The new session API that uses TF_Graph*. The intent is this will
// replace the TF_ExtendGraph() API. // replace the TF_ExtendGraph() API.
// TODO(josh11b): Rename this TF_Session once we delete the old API. // TODO(ashankar,josh11b): Rename this to TF_Session before v1.0.
typedef struct TF_SessionWithGraph TF_SessionWithGraph; typedef struct TF_SessionWithGraph TF_SessionWithGraph;
// Return a new execution session with the associated graph, or NULL // Return a new execution session with the associated graph, or NULL
@ -808,7 +808,30 @@ extern void TF_CloseSessionWithGraph(TF_SessionWithGraph*, TF_Status* status);
// TODO(josh11b): Rename this TF_DeleteSession() once we delete the old API. // TODO(josh11b): Rename this TF_DeleteSession() once we delete the old API.
extern void TF_DeleteSessionWithGraph(TF_SessionWithGraph*, TF_Status* status); extern void TF_DeleteSessionWithGraph(TF_SessionWithGraph*, TF_Status* status);
// See TF_Run() below. // Run the graph associated with the session starting with the supplied inputs
// (inputs[0,ninputs-1] with corresponding values in input_values[0,ninputs-1])/
// Regardless of success or failure, the TF_SessionRun call takes ownership the
// elements of input_values and will eventually call TF_DeleteTensor on them.
//
// Any NULL and non-NULL value combinations for (`run_options`,
// `run_metadata`) are valid.
//
// - `run_options` may be NULL, in which case it will be ignored; or
// non-NULL, in which case it must point to a `TF_Buffer` containing the
// serialized representation of a `RunOptions` protocol buffer.
// - `run_metadata` may be NULL, in which case it will be ignored; or
// non-NULL, in which case it must point to an empty, freshly allocated
// `TF_Buffer` that may be updated to contain the serialized representation
// of a `RunMetadata` protocol buffer.
//
// The caller retains the ownership of `run_options` and/or `run_metadata` (when
// not NULL) and should manually call TF_DeleteBuffer on them.
//
// On success, the tensors corresponding to outputs[0,noutputs-1] are placed in
// output_values[]. Ownership of the elements of output_values[] is transferred
// to the caller, which must eventually call TF_DeleteTensor on them.
//
// On failure, output_values[] contains NULLs.
extern void TF_SessionRun(TF_SessionWithGraph* session, extern void TF_SessionRun(TF_SessionWithGraph* session,
// RunOptions // RunOptions
const TF_Buffer* run_options, const TF_Buffer* run_options,
@ -825,7 +848,14 @@ extern void TF_SessionRun(TF_SessionWithGraph* session,
// Output status // Output status
TF_Status*); TF_Status*);
// See TF_PRunSetup() below. // Set up the graph with the intended feeds (inputs) and fetches (outputs) for a
// sequence of partial run calls.
//
// On success, returns a handle that is used for subsequent PRun calls.
//
// On failure, out_status contains a tensorflow::Status with an error
// message.
// NOTE: This is EXPERIMENTAL and subject to change.
extern void TF_SessionPRunSetup(TF_SessionWithGraph*, extern void TF_SessionPRunSetup(TF_SessionWithGraph*,
// Input names // Input names
const TF_Port* inputs, int ninputs, const TF_Port* inputs, int ninputs,
@ -839,7 +869,9 @@ extern void TF_SessionPRunSetup(TF_SessionWithGraph*,
// Output status // Output status
TF_Status*); TF_Status*);
// See TF_PRun() below. // Continue to run the graph with additional feeds and fetches. The
// execution state is uniquely identified by the handle.
// NOTE: This is EXPERIMENTAL and subject to change.
extern void TF_SessionPRun(TF_SessionWithGraph*, const char* handle, extern void TF_SessionPRun(TF_SessionWithGraph*, const char* handle,
// Input tensors // Input tensors
const TF_Port* inputs, const TF_Port* inputs,
@ -855,19 +887,21 @@ extern void TF_SessionPRun(TF_SessionWithGraph*, const char* handle,
// -------------------------------------------------------------------------- // --------------------------------------------------------------------------
// The deprecated session API. Please switch to the above instead of // The deprecated session API. Please switch to the above instead of
// TF_ExtendGraph(). TF_Session manages a single graph and execution. // TF_ExtendGraph(). TF_DeprecatedSession manages a single graph and execution.
typedef struct TF_Session TF_Session; typedef struct TF_DeprecatedSession TF_DeprecatedSession;
// Return a new execution session, or NULL on error. // Return a new execution session, or NULL on error.
extern TF_Session* TF_NewSession(const TF_SessionOptions*, TF_Status* status); extern TF_DeprecatedSession* TF_NewDeprecatedSession(const TF_SessionOptions*,
TF_Status* status);
// Close a session. // Close a session.
extern void TF_CloseSession(TF_Session*, TF_Status* status); extern void TF_CloseDeprecatedSession(TF_DeprecatedSession*, TF_Status* status);
// Destroy a session. Even if error information is recorded in *status, // Destroy a session. Even if error information is recorded in *status,
// this call discards all resources associated with the session. // this call discards all resources associated with the session.
extern void TF_DeleteSession(TF_Session*, TF_Status* status); extern void TF_DeleteDeprecatedSession(TF_DeprecatedSession*,
TF_Status* status);
// Closes all existing sessions connected to the `target` specified in the // Closes all existing sessions connected to the `target` specified in the
// `SessionOptions`, and frees shared resources in `containers` on `target'. // `SessionOptions`, and frees shared resources in `containers` on `target'.
@ -877,35 +911,11 @@ extern void TF_Reset(const TF_SessionOptions* opt, const char** containers,
// Treat the bytes proto[0,proto_len-1] as a serialized GraphDef and // Treat the bytes proto[0,proto_len-1] as a serialized GraphDef and
// add the nodes in that GraphDef to the graph for the session. // add the nodes in that GraphDef to the graph for the session.
extern void TF_ExtendGraph(TF_Session*, const void* proto, size_t proto_len, extern void TF_ExtendGraph(TF_DeprecatedSession*, const void* proto,
TF_Status*); size_t proto_len, TF_Status*);
// Run the graph associated with the session starting with the // See TF_SessionRun() above.
// supplied inputs (inputs[0,ninputs-1]). Regardless of success or extern void TF_Run(TF_DeprecatedSession*,
// failure, inputs[] become the property of the implementation (the
// implementation will eventually call TF_DeleteTensor on each input).
//
// Any NULL and non-NULL value combinations for (`run_options`,
// `run_metadata`) are valid.
//
// - `run_options` may be NULL, in which case it will be ignored; or
// non-NULL, in which case it must point to a `TF_Buffer` containing the
// serialized representation of a `RunOptions` protocol buffer.
// - `run_metadata` may be NULL, in which case it will be ignored; or
// non-NULL, in which case it must point to an empty, freshly allocated
// `TF_Buffer` that may be updated to contain the serialized representation
// of a `RunMetadata` protocol buffer.
//
// The caller retains the ownership of `run_options` and/or `run_metadata` (when
// not NULL) and should manually call TF_DeleteBuffer on them.
//
// On success, the tensors corresponding to output_names[0,noutputs-1]
// are placed in outputs[], and these outputs[] become the property
// of the caller (the caller must eventually call TF_DeleteTensor on
// them).
//
// On failure, outputs[] contains NULLs.
extern void TF_Run(TF_Session*,
// RunOptions // RunOptions
const TF_Buffer* run_options, const TF_Buffer* run_options,
// Input tensors // Input tensors
@ -919,15 +929,8 @@ extern void TF_Run(TF_Session*,
// Output status // Output status
TF_Status*); TF_Status*);
// Set up the graph with the intended feeds and fetches for a sequence // See TF_SessionPRunSetup() above.
// of partial run calls. extern void TF_PRunSetup(TF_DeprecatedSession*,
//
// On success, returns a handle that is used for subsequent PRun calls.
//
// On failure, out_status contains a tensorflow::Status with an error
// message.
// NOTE: This is EXPERIMENTAL and subject to change.
extern void TF_PRunSetup(TF_Session*,
// Input names // Input names
const char** input_names, int ninputs, const char** input_names, int ninputs,
// Output names // Output names
@ -939,10 +942,8 @@ extern void TF_PRunSetup(TF_Session*,
// Output status // Output status
TF_Status*); TF_Status*);
// Continue to run the graph with additional feeds and fetches. The // See TF_SessionPRun above.
// execution state is uniquely identified by the handle. extern void TF_PRun(TF_DeprecatedSession*, const char* handle,
// NOTE: This is EXPERIMENTAL and subject to change.
extern void TF_PRun(TF_Session*, const char* handle,
// Input tensors // Input tensors
const char** input_names, TF_Tensor** inputs, int ninputs, const char** input_names, TF_Tensor** inputs, int ninputs,
// Output tensors // Output tensors

View File

@ -157,7 +157,7 @@ TEST(CAPI, SessionOptions) {
TEST(CAPI, SessionWithRunMetadata) { TEST(CAPI, SessionWithRunMetadata) {
TF_Status* s = TF_NewStatus(); TF_Status* s = TF_NewStatus();
TF_SessionOptions* opt = TF_NewSessionOptions(); TF_SessionOptions* opt = TF_NewSessionOptions();
TF_Session* session = TF_NewSession(opt, s); TF_DeprecatedSession* session = TF_NewDeprecatedSession(opt, s);
TF_DeleteSessionOptions(opt); TF_DeleteSessionOptions(opt);
ASSERT_EQ(TF_OK, TF_GetCode(s)) << TF_Message(s); ASSERT_EQ(TF_OK, TF_GetCode(s)) << TF_Message(s);
@ -171,7 +171,7 @@ TEST(CAPI, SessionWithRunMetadata) {
TF_DeleteBuffer(run_metadata); TF_DeleteBuffer(run_metadata);
TF_DeleteBuffer(run_options); TF_DeleteBuffer(run_options);
TF_DeleteSession(session, s); TF_DeleteDeprecatedSession(session, s);
ASSERT_EQ(TF_OK, TF_GetCode(s)) << TF_Message(s); ASSERT_EQ(TF_OK, TF_GetCode(s)) << TF_Message(s);
TF_DeleteStatus(s); TF_DeleteStatus(s);

View File

@ -500,7 +500,7 @@ class BaseSession(SessionInterface):
opts = tf_session.TF_NewSessionOptions(target=self._target, config=config) opts = tf_session.TF_NewSessionOptions(target=self._target, config=config)
try: try:
with errors.raise_exception_on_not_ok_status() as status: with errors.raise_exception_on_not_ok_status() as status:
self._session = tf_session.TF_NewSession(opts, status) self._session = tf_session.TF_NewDeprecatedSession(opts, status)
finally: finally:
tf_session.TF_DeleteSessionOptions(opts) tf_session.TF_DeleteSessionOptions(opts)
@ -517,7 +517,7 @@ class BaseSession(SessionInterface):
if self._opened and not self._closed: if self._opened and not self._closed:
self._closed = True self._closed = True
with errors.raise_exception_on_not_ok_status() as status: with errors.raise_exception_on_not_ok_status() as status:
tf_session.TF_CloseSession(self._session, status) tf_session.TF_CloseDeprecatedSession(self._session, status)
def __del__(self): def __del__(self):
# cleanly ignore all exceptions # cleanly ignore all exceptions
@ -528,7 +528,7 @@ class BaseSession(SessionInterface):
if self._session is not None: if self._session is not None:
try: try:
status = tf_session.TF_NewStatus() status = tf_session.TF_NewStatus()
tf_session.TF_DeleteSession(self._session, status) tf_session.TF_DeleteDeprecatedSession(self._session, status)
finally: finally:
tf_session.TF_DeleteStatus(status) tf_session.TF_DeleteStatus(status)
self._session = None self._session = None

View File

@ -170,9 +170,9 @@ tensorflow::ImportNumpy();
%rename("_TF_SetConfig") TF_SetConfig; %rename("_TF_SetConfig") TF_SetConfig;
%rename("_TF_NewSessionOptions") TF_NewSessionOptions; %rename("_TF_NewSessionOptions") TF_NewSessionOptions;
%unignore TF_DeleteSessionOptions; %unignore TF_DeleteSessionOptions;
%unignore TF_NewSession; %unignore TF_NewDeprecatedSession;
%unignore TF_CloseSession; %unignore TF_CloseDeprecatedSession;
%unignore TF_DeleteSession; %unignore TF_DeleteDeprecatedSession;
%unignore TF_ExtendGraph; %unignore TF_ExtendGraph;
%unignore TF_NewLibrary; %unignore TF_NewLibrary;
%unignore TF_LoadLibrary; %unignore TF_LoadLibrary;

View File

@ -393,7 +393,7 @@ Safe_PyObjectPtr make_safe(PyObject* o) {
return Safe_PyObjectPtr(o, Py_DECREF_wrapper); return Safe_PyObjectPtr(o, Py_DECREF_wrapper);
} }
void TF_Run_wrapper_helper(TF_Session* session, const char* handle, void TF_Run_wrapper_helper(TF_DeprecatedSession* session, const char* handle,
const TF_Buffer* run_options, PyObject* feed_dict, const TF_Buffer* run_options, PyObject* feed_dict,
const NameVector& output_names, const NameVector& output_names,
const NameVector& target_nodes, const NameVector& target_nodes,
@ -547,7 +547,7 @@ void TF_Run_wrapper_helper(TF_Session* session, const char* handle,
// Wrapper for TF_Run that converts the arguments to appropriate types. // Wrapper for TF_Run that converts the arguments to appropriate types.
// If *out_status is OK, the caller becomes the owner of the PyObjects // If *out_status is OK, the caller becomes the owner of the PyObjects
// in *out_values. // in *out_values.
void TF_Run_wrapper(TF_Session* session, const TF_Buffer* run_options, void TF_Run_wrapper(TF_DeprecatedSession* session, const TF_Buffer* run_options,
PyObject* feed_dict, const NameVector& output_names, PyObject* feed_dict, const NameVector& output_names,
const NameVector& target_nodes, TF_Status* out_status, const NameVector& target_nodes, TF_Status* out_status,
PyObjectVector* out_values, TF_Buffer* run_outputs) { PyObjectVector* out_values, TF_Buffer* run_outputs) {
@ -557,7 +557,8 @@ void TF_Run_wrapper(TF_Session* session, const TF_Buffer* run_options,
// Wrapper for TF_PRunSetup that converts the arguments to appropriate types. // Wrapper for TF_PRunSetup that converts the arguments to appropriate types.
// If *out_status is OK, the caller becomes the owner of *out_handle. // If *out_status is OK, the caller becomes the owner of *out_handle.
void TF_PRunSetup_wrapper(TF_Session* session, const NameVector& input_names, void TF_PRunSetup_wrapper(TF_DeprecatedSession* session,
const NameVector& input_names,
const NameVector& output_names, const NameVector& output_names,
const NameVector& target_nodes, TF_Status* out_status, const NameVector& target_nodes, TF_Status* out_status,
const char** out_handle) { const char** out_handle) {
@ -573,7 +574,7 @@ void TF_PRunSetup_wrapper(TF_Session* session, const NameVector& input_names,
// Wrapper for TF_PRun that converts the arguments to appropriate types. // Wrapper for TF_PRun that converts the arguments to appropriate types.
// If *out_status is OK, the caller becomes the owner of the PyObjects // If *out_status is OK, the caller becomes the owner of the PyObjects
// in *out_values. // in *out_values.
void TF_PRun_wrapper(TF_Session* session, const char* handle, void TF_PRun_wrapper(TF_DeprecatedSession* session, const char* handle,
PyObject* feed_dict, const NameVector& output_names, PyObject* feed_dict, const NameVector& output_names,
TF_Status* out_status, PyObjectVector* out_values) { TF_Status* out_status, PyObjectVector* out_values) {
TF_Run_wrapper_helper(session, handle, nullptr, feed_dict, output_names, TF_Run_wrapper_helper(session, handle, nullptr, feed_dict, output_names,

View File

@ -59,7 +59,7 @@ Safe_PyObjectPtr make_safe(PyObject* o);
// //
// On failure, out_status contains a tensorflow::Status with an error // On failure, out_status contains a tensorflow::Status with an error
// message. // message.
void TF_Run_wrapper(TF_Session* session, const TF_Buffer* run_options, void TF_Run_wrapper(TF_DeprecatedSession* session, const TF_Buffer* run_options,
PyObject* feed_dict, const NameVector& output_names, PyObject* feed_dict, const NameVector& output_names,
const NameVector& target_nodes, TF_Status* out_status, const NameVector& target_nodes, TF_Status* out_status,
PyObjectVector* out_values, TF_Buffer* run_outputs); PyObjectVector* out_values, TF_Buffer* run_outputs);
@ -73,7 +73,8 @@ void TF_Run_wrapper(TF_Session* session, const TF_Buffer* run_options,
// message. // message.
// //
// NOTE: This is EXPERIMENTAL and subject to change. // NOTE: This is EXPERIMENTAL and subject to change.
void TF_PRunSetup_wrapper(TF_Session* session, const NameVector& input_names, void TF_PRunSetup_wrapper(TF_DeprecatedSession* session,
const NameVector& input_names,
const NameVector& output_names, const NameVector& output_names,
const NameVector& target_nodes, TF_Status* out_status, const NameVector& target_nodes, TF_Status* out_status,
const char** out_handle); const char** out_handle);
@ -92,7 +93,7 @@ void TF_PRunSetup_wrapper(TF_Session* session, const NameVector& input_names,
// message. // message.
// //
// NOTE: This is EXPERIMENTAL and subject to change. // NOTE: This is EXPERIMENTAL and subject to change.
void TF_PRun_wrapper(TF_Session* session, const char* handle, void TF_PRun_wrapper(TF_DeprecatedSession* session, const char* handle,
PyObject* feed_dict, const NameVector& output_names, PyObject* feed_dict, const NameVector& output_names,
TF_Status* out_status, PyObjectVector* out_values); TF_Status* out_status, PyObjectVector* out_values);