1/* Copyright 2016 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
16syntax = "proto3";
17
18package tensorflow.grpc;
19option java_outer_classname = "MasterServiceProtos";
20option java_multiple_files = true;
21option java_package = "org.tensorflow.distruntime";
22option go_package = "github.com/tensorflow/tensorflow/tensorflow/go/core/protobuf";
23import "tensorflow/core/protobuf/master.proto";
24
25////////////////////////////////////////////////////////////////////////////////
26//
27// MasterService defines a TensorFlow service with which a client can
28// interact to execute a distributed TensorFlow computation.
29//
30// A master service keeps track of multiple "master sessions". Each
31// session encapsulates a computation graph and its associated state,
32// and typically corresponds to a single "client session" (e.g. a
33// `tensorflow::Session` instance).
34//
35// A session is responsible for the following:
36// * assigning each node to a device (locally or remotely) using a
37//   placement algorithm. This may make decisions based on collected
38//   statistics from the workers in the system (e.g., memory usage,
39//   bandwidth consumption, etc.)
40//
41// * inserting intermediate nodes and edges to support cross-device
42//   and cross-process data flows and resource management.
43//
44// * issuing commands to workers to execute the subgraphs associated
45//   with those workers.
46//
47// Typically, a client carries out an iterative computation
48// (e.g. training) by invoking RPCs against the master in a
49// client-side loop. The client first creates a client session that
50// connects to a particular master (using gRPC for example). The
51// master creates a corresponding master session that is hosted on
52// the master and caches state between the client's invocations.
53//
54// After the session is established, the master returns an opaque
55// handle to the client that can be used to associate the client and
56// master sessions.
57//
58// The client may send an initial graph to the master in the
59// CreateSession call, and add nodes to the graph using ExtendSession.
60//
61// The most frequent operation a master is "RunStep", which implements
62// the `Session::Run()` API. It supports feeding in arguments,
63// executing a dataflow computation, and fetching arguments.
64//
65// Finally, when the client no longer needs the session, it should
66// close the session by invoking CloseSession, which allows the master
67// to reclaim resources associated with the session. The master may
68// implement a garbage collection scheme that closes sessions that
69// have been inactive for some time.
70//
71// For example, the following pseudo-code illustrates how a client
72// interacts with a master:
73//
74// stub = NewStub("/job:mnist/replica:0/task:0")
75// {handle} = stub->CreateSession({graph_def})
76// do {
77//   stub->RunStep({handle, {feeds}, {fetches}})
78//   // The client can evaluate a predicate locally, based on the
79//   // result of `fetches`, to determine whether to terminate. For
80//   // example, it might fetch the loss and evaluate whether it is less
81//   // than some threshold.
82// } while (!should_stop({fetches}));
83// stub->CloseSession({handle})
84//
85////////////////////////////////////////////////////////////////////////////////
86
87service MasterService {
88  // Creates a session.
89  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
90
91  // Extends a session.
92  rpc ExtendSession(ExtendSessionRequest) returns (ExtendSessionResponse);
93
94  // Prepares future partial run calls.
95  rpc PartialRunSetup(PartialRunSetupRequest) returns (PartialRunSetupResponse);
96
97  // Drives the graph computation.
98  rpc RunStep(RunStepRequest) returns (RunStepResponse);
99
100  // Closes a session.
101  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
102
103  // List the devices usable by the master.
104  rpc ListDevices(ListDevicesRequest) returns (ListDevicesResponse);
105
106  // Close and abandon all existing sessions.  Ongoing computations
107  // will no longer affect fresh ones via the resources in containers listed in
108  // the ResetRequest.  See ResetRequest for more details.
109  rpc Reset(ResetRequest) returns (ResetResponse);
110
111  // Registers a callable for execution with RunCallable.
112  rpc MakeCallable(MakeCallableRequest) returns (MakeCallableResponse);
113
114  // Executes a callable registered with MakeCallable.
115  rpc RunCallable(RunCallableRequest) returns (RunCallableResponse);
116
117  // Frees resources associated with a callable registered with MakeCallable.
118  rpc ReleaseCallable(ReleaseCallableRequest) returns (ReleaseCallableResponse);
119}
120