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