executor.proto

syntax = "proto3";

package tensorflow_federated.v0;

import "federated_language/proto/array.proto";
import "federated_language/proto/computation.proto";

// A service providing computation execution.
service ExecutorGroup {
  // Returns a
  rpc GetExecutor(GetExecutorRequest) returns (GetExecutorResponse) {}

  // Creates a value in the executor and returns a reference to it that can be
  // supplied as an argument to other methods.
  rpc CreateValue(CreateValueRequest) returns (CreateValueResponse) {}

  // Creates a call in the executor and returns a reference to the result.
  rpc CreateCall(CreateCallRequest) returns (CreateCallResponse) {}

  // Creates a struct of values in the executor and returns a reference to it.
  rpc CreateStruct(CreateStructRequest) returns (CreateStructResponse) {}

  // Creates a selection from an executor value and returns a reference to it.
  rpc CreateSelection(CreateSelectionRequest)
      returns (CreateSelectionResponse) {}

  // Causes a value in the executor to get computed, and sends back the result.
  // WARNING: Unlike all other methods in this API, this may be a long-running
  // call (it will block until the value becomes available).
  rpc Compute(ComputeRequest) returns (ComputeResponse) {}

  // TODO: b/134543154 - Given that there is no support for asynchronous server
  // processing in Python gRPC, long-running calls may be a problem. Revisit
  // this and look for alternatives.

  // Causes one or more values in the executor to get disposed of (no longer
  // available for future calls).
  rpc Dispose(DisposeRequest) returns (DisposeResponse) {}

  // Causes an executor to be disposed of (no longer available for future
  // calls).
  rpc DisposeExecutor(DisposeExecutorRequest)
      returns (DisposeExecutorResponse) {}
}

message Cardinality {
  federated_language.Placement placement = 1;
  int32 cardinality = 2;
}

message GetExecutorRequest {
  repeated Cardinality cardinalities = 1;
}

message GetExecutorResponse {
  ExecutorId executor = 1;
}

// An identifier for a particular executor within an `ExecutorGroup`.
message ExecutorId {
  string id = 1;
}

message CreateValueRequest {
  Value value = 1;
  ExecutorId executor = 2;
}

message CreateValueResponse {
  ValueRef value_ref = 1;
}

message CreateCallRequest {
  // A reference to the function to be called (which must be obtained from a
  // prior call to `CreateValue()`).
  ValueRef function_ref = 1;

  // An optional argument, only for functions that declare an argument.
  ValueRef argument_ref = 2;

  ExecutorId executor = 3;
}

message CreateCallResponse {
  ValueRef value_ref = 1;
}

message CreateStructRequest {
  repeated Element element = 1;
  message Element {
    string name = 1;
    ValueRef value_ref = 2;
  }
  ExecutorId executor = 3;
}

message CreateStructResponse {
  ValueRef value_ref = 1;
}

message CreateSelectionRequest {
  ValueRef source_ref = 1;
  int32 index = 3;
  ExecutorId executor = 4;
}

message CreateSelectionResponse {
  ValueRef value_ref = 1;
}

message ComputeRequest {
  ValueRef value_ref = 1;
  ExecutorId executor = 2;
}

message ComputeResponse {
  Value value = 1;
}

message DisposeRequest {
  repeated ValueRef value_ref = 1;
  ExecutorId executor = 2;
}

message DisposeResponse {}

message DisposeExecutorRequest {
  ExecutorId executor = 1;
}

message DisposeExecutorResponse {}

// A representation of a value that's to be embedded in the executor, or that
// is being returned as a result of a computation.
message Value {
  // A representation of a struct of values. Unlike in the computation proto,
  // elements of this struct can contain actual computed values such as
  // serialized tensors (rather than computations).
  message Struct {
    repeated Element element = 1;
    message Element {
      string name = 1;
      Value value = 2;
    }
  }

  // A representation of a sequence value.
  message Sequence {
    // The TensorFlow Federated `Type` of the elements in this
    // sequence.
    federated_language.Type element_type = 2;

    // A representation of a sequence of values.
    message Element {
      repeated federated_language.Array flat_value = 1;
    }
    repeated Element element = 4;

    reserved 1;  // bytes zipped_saved_model
    reserved 3;  // bytes serialized_graph_def
  }

  // A representation of a federated value.
  message Federated {
    // The type of the federated value.
    federated_language.FederatedType type = 1;

    // The member constituents, one per participant in the collective defined
    // by this value's placement within the executor.
    repeated Value value = 2;
  }

  oneof value {
    // An array value.
    federated_language.Array array = 6;

    // A serialized TFF computation; this is the canonical (and currently only)
    // way to pass any functional constructs, but the computation included here
    // does not necessarily have to be of a functional type.
    federated_language.Computation computation = 2;

    // A struct of values.
    Struct struct = 3;

    // A sequence of values.
    Sequence sequence = 4;

    // A value of a federated type.
    Federated federated = 5;
  }

  reserved 1;  // google.protobuf.Any tensor
}

// A reference to a value embedded in the executor, guaranteed to be unique
// at a minimum among all the values that have been embedded in this executor
// instance (but not guaranteed to be unique globally across the network),
// across the agreed-upon lifetime of the service (at the very least, reboots
// of the backend instance while the client is running should not result in
// name clashes). In the context of a simulation, the service lifetime should
// at minimum span the lifetime of the entire simulation.
message ValueRef {
  // The identifier should consist of printable ASCII characters for the sake
  // of debuggability, ideally alphanumeric. The format of the identifier may
  // depend on the type of the executor.
  string id = 1;
}