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

RELEASE.md

@@ -8,6 +8,8 @@ BUS_ANY was used.
 * `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
   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
 

tensorflow/c/c_api.cc

@@ -253,33 +253,34 @@ void TF_DeleteBuffer(TF_Buffer* buffer) {
 TF_Buffer TF_GetBuffer(TF_Buffer* buffer) { return *buffer; }
 
 // --------------------------------------------------------------------------
-struct TF_Session {
+struct TF_DeprecatedSession {
   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;
   status->status = NewSession(opt->options, &session);
   if (status->status.ok()) {
-    return new TF_Session({session});
+    return new TF_DeprecatedSession({session});
   } else {
     DCHECK_EQ(nullptr, session);
     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();
 }
 
-void TF_DeleteSession(TF_Session* s, TF_Status* status) {
+void TF_DeleteDeprecatedSession(TF_DeprecatedSession* s, TF_Status* status) {
   status->status = Status::OK();
   delete s->session;
   delete s;
 }
 
-void TF_ExtendGraph(TF_Session* s, const void* proto, size_t proto_len,
-                    TF_Status* status) {
+void TF_ExtendGraph(TF_DeprecatedSession* s, const void* proto,
+                    size_t proto_len, TF_Status* status) {
   GraphDef g;
   if (!tensorflow::ParseProtoUnlimited(&g, proto, proto_len)) {
     status->status = InvalidArgument("Invalid GraphDef");
@@ -531,7 +532,7 @@ static void TF_Run_Helper(
 
 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
             const char** c_input_names, TF_Tensor** c_inputs, int ninputs,
             // 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);
 }
 
-void TF_PRunSetup(TF_Session* s,
+void TF_PRunSetup(TF_DeprecatedSession* s,
                   // Input names
                   const char** c_input_names, int ninputs,
                   // 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
              const char** c_input_names, TF_Tensor** c_inputs, int ninputs,
              // Output tensors

tensorflow/c/c_api.h

@@ -784,7 +784,7 @@ extern void TF_OperationToNodeDef(TF_Operation* oper,
 // The new session API that uses TF_Graph*.  The intent is this will
 // 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;
 
 // 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.
 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,
                           // RunOptions
                           const TF_Buffer* run_options,
@@ -825,7 +848,14 @@ extern void TF_SessionRun(TF_SessionWithGraph* session,
                           // Output 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*,
                                 // Input names
                                 const TF_Port* inputs, int ninputs,
@@ -839,7 +869,9 @@ extern void TF_SessionPRunSetup(TF_SessionWithGraph*,
                                 // Output 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,
                            // Input tensors
                            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
-// 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.
-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.
-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,
 // 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
 // `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
 // 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,
-                           TF_Status*);
+extern void TF_ExtendGraph(TF_DeprecatedSession*, const void* proto,
+                           size_t proto_len, TF_Status*);
 
-// Run the graph associated with the session starting with the
-// supplied inputs (inputs[0,ninputs-1]).  Regardless of success or
-// 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*,
+// See TF_SessionRun() above.
+extern void TF_Run(TF_DeprecatedSession*,
                    // RunOptions
                    const TF_Buffer* run_options,
                    // Input tensors
@@ -919,15 +929,8 @@ extern void TF_Run(TF_Session*,
                    // Output status
                    TF_Status*);
 
-// Set up the graph with the intended feeds and fetches 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_PRunSetup(TF_Session*,
+// See TF_SessionPRunSetup() above.
+extern void TF_PRunSetup(TF_DeprecatedSession*,
                          // Input names
                          const char** input_names, int ninputs,
                          // Output names
@@ -939,10 +942,8 @@ extern void TF_PRunSetup(TF_Session*,
                          // Output status
                          TF_Status*);
 
-// 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_PRun(TF_Session*, const char* handle,
+// See TF_SessionPRun above.
+extern void TF_PRun(TF_DeprecatedSession*, const char* handle,
                     // Input tensors
                     const char** input_names, TF_Tensor** inputs, int ninputs,
                     // Output tensors

tensorflow/c/c_api_test.cc

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

tensorflow/python/client/session.py

@@ -500,7 +500,7 @@ def __init__(self, target='', graph=None, config=None):
     opts = tf_session.TF_NewSessionOptions(target=self._target, config=config)
     try:
       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:
       tf_session.TF_DeleteSessionOptions(opts)
 
@@ -517,7 +517,7 @@ def close(self):
       if self._opened and not self._closed:
         self._closed = True
         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):
     # cleanly ignore all exceptions
@@ -528,7 +528,7 @@ def __del__(self):
     if self._session is not None:
       try:
         status = tf_session.TF_NewStatus()
-        tf_session.TF_DeleteSession(self._session, status)
+        tf_session.TF_DeleteDeprecatedSession(self._session, status)
       finally:
         tf_session.TF_DeleteStatus(status)
       self._session = None

tensorflow/python/client/tf_session.i

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

tensorflow/python/client/tf_session_helper.cc

@@ -393,7 +393,7 @@ Safe_PyObjectPtr make_safe(PyObject* o) {
   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 NameVector& output_names,
                            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.
 // If *out_status is OK, the caller becomes the owner of the PyObjects
 // 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,
                     const NameVector& target_nodes, TF_Status* out_status,
                     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.
 // 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& target_nodes, TF_Status* out_status,
                           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.
 // If *out_status is OK, the caller becomes the owner of the PyObjects
 // 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,
                      TF_Status* out_status, PyObjectVector* out_values) {
   TF_Run_wrapper_helper(session, handle, nullptr, feed_dict, output_names,

tensorflow/python/client/tf_session_helper.h

@@ -59,7 +59,7 @@ Safe_PyObjectPtr make_safe(PyObject* o);
 //
 // On failure, out_status contains a tensorflow::Status with an error
 // 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,
                     const NameVector& target_nodes, TF_Status* out_status,
                     PyObjectVector* out_values, TF_Buffer* run_outputs);
@@ -73,7 +73,8 @@ void TF_Run_wrapper(TF_Session* session, const TF_Buffer* run_options,
 // message.
 //
 // 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& target_nodes, TF_Status* out_status,
                           const char** out_handle);
@@ -92,7 +93,7 @@ void TF_PRunSetup_wrapper(TF_Session* session, const NameVector& input_names,
 // message.
 //
 // 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,
                      TF_Status* out_status, PyObjectVector* out_values);