RPC Service Reference

This document describes the remote procedure call (RPC) client/service architecture that CompilerGym to separate the user frontend code from the compiler backends.

How it Works
CompilerGymService
Request and Reply Messages
Core Message Types

How it Works 

The file compiler_gym/service/proto/compiler_gym_service.proto defines a CompilerGymService, which is an interface that can be used by compilers to expose the incremental compilation of a program as an interactive environment. The service is defined using gRPC, and the individual requests and responses are defined using protocol buffers. The protocol buffer schema is then used to generate bindings in a programming language of choice.

Protocol buffers support a wide range of programming languages, allowing compiler developers to expose their optimization problems in whatever language makes sense for them. For Python and C++ we also provide a common runtime that offers a higher level of abstraction and takes care of much of the boilerplate required for RPC communication. For further details check out the C++ or Python class documentation.

CompilerGymService 

namespace CompilerGymService

The CompilerGymService is the interface that exposes the incremental optimization of a program as an interactive environment.

Functions

rpc GetVersion (GetVersionRequest) returns(GetVersionReply): Request version strings from the service.

rpc GetSpaces (GetSpacesRequest) returns(GetSpacesReply)

Request the action and observation spaces that this service supports.

The service responds with an initial action space, and a list of available observation and reward spaces.

rpc StartSession (StartSessionRequest) returns(StartSessionReply)

Start a new CompilerGym service session.

This allocates a new session on the service and returns a session ID. To terminate the session, call EndSession() once done. Raises grpc::StatusCode::NOT_FOUND if the requested benchmark URI is not found.

rpc ForkSession (ForkSessionRequest) returns(ForkSessionReply)

Fork a session.

This creates a new session in exactly the same state. The new session must be terminated with EndSession() once done. This returns an error if the session to fork does not exist.

rpc EndSession (EndSessionRequest) returns(EndSessionReply)

End a CompilerGym service session.

If the requested session does not exist, this returns an error.

rpc Step (StepRequest) returns(StepReply)

Apply a list of optimization decisions and compute a list of observations for a session.

Optimization decisions are selected from the last ActionSpace returned by a call to GetSpaces() or Step(). Valid observations are queried using GetSpaces(). This returns an error if the requested session does not exist.

rpc AddBenchmark (AddBenchmarkRequest) returns(AddBenchmarkReply): Register a new benchmark.

rpc SendSessionParameter (SendSessionParameterRequest) returns(SendSessionParameterReply)

Transmit <key, value> parameters to a session.

Each parameter generates a string response. It us up to the client/service to agree on a common schema for encoding and decoding these parameters. An unknown key/value returns grpc::StatusCode::INVALID_ARGUMENT.

Request and Reply Messages 

struct GetVersionRequest: A GetVersion() request.

struct GetVersionReply

The GetVersion() response.

Public Members

string service_version = 1: The version string for this service.

string compiler_version = 2: The version string for the underlying compiler.

struct GetSpacesRequest: A GetSpaces() request.

struct GetSpacesReply

A GetSpaces() reply.

Public Members

repeated ActionSpace action_space_list = 1: A list of one or more action spaces that the service supports.

repeated ObservationSpace observation_space_list = 2

A list of available observation spaces.

A service may support one or more observation spaces.

struct StartSessionRequest

A StartSession() request.

Public Members

Benchmark benchmark = 4: The benchmark to use.

int32 action_space = 2

An index into the GetSpacesReply.action_space_list selecting the action space that is to be used for this session.

Once set, the action space cannot be changed for the duration of the session.

repeated int32 observation_space = 3: A list of indices into the GetSpacesReply.observation_space_list.

struct StartSessionReply

A StartSession() reply.

Public Members

int64 session_id = 1

The ID that has been assigned to the session.

The client must use this ID in all subsequent interactions with the service for this session.

ActionSpace new_action_space = 3

A new action space.

This is set only if, after initializing the session, the action space has changed from the default action space returned by GetSpaces(). If set, the environment should discard the previous action space and replace it with this one. Else, the action space remains unchanged.

repeated Event observation = 4: Observed states after completing the action.

struct ForkSessionRequest

A Fork() request.

Public Members

int64 session_id = 1: The ID of the session to fork.

struct ForkSessionReply

A Fork() reply.

Public Members

int64 session_id = 1: The ID of the newly created session.

struct EndSessionRequest

An EndSession() request.

Public Members

int64 session_id = 1: The ID of the session.

struct EndSessionReply

An EndSession() reply.

Public Members

int32 remaining_sessions = 1: The number of sessions that the service currently has.

struct StepRequest

A Step() request.

Public Members

int64 session_id = 1: The ID of the session.

repeated Event action = 2: A list of actions to execute, in order.

repeated int32 observation_space = 3: A list of indices into the GetSpacesReply.observation_space_list.

struct StepReply

A Step() reply.

Public Members

bool end_of_session = 1

Indicates that the session has ended.

This could be because there are no further actions that can be made, or because the action has led to an invalid state. Once this field has been set, you should make no further calls to step(). However, you mays still request reward and new observations.

bool action_had_no_effect = 2

A service may set this field to true if the action is known not to have any effect.

This allows an agent to assume that observations or rewards computed before this action remain valid, providing that they are deterministic.

ActionSpace new_action_space = 3

A new action space.

This field is set if, as a result of running the requested action, the action space has changed. Else, the action space remains unchanged.

repeated Event observation = 4: Observed states after completing the action.

struct AddBenchmarkRequest

An AddBenchmark() request.

Public Members

repeated Benchmark benchmark = 1: A list of benchmarks to add.

struct AddBenchmarkReply: An AddBenchmark() reply.

struct SendSessionParameterRequest

A SendSessionParameter() request.

Public Members

int64 session_id = 1: The ID of the session.

repeated SessionParameter parameter = 2: A list of <key, value> parameters to pass to the session.

struct SendSessionParameterReply

A SendSessionParameter() reply.

Public Members

repeated string reply = 1: A list of response messages, one per parameter request.

Core Message Types 

struct ActionSpace

struct ObservationSpace

Public Members

bool deterministic = 3: Whether the observation space is deterministic.

bool platform_dependent = 4: Whether the observations depend on the service execution environment.

Event default_observation = 5

A default observation.

This value should be used by the client in lieu of a true observation if the compiler service terminates abruptly, such as a crash while applying an action.

struct Event

Common structure shared between actions and observations.

Public Members

BooleanTensor boolean_tensor = 9: Fixed and variable length sequences are represented as one-dimensional tensor.

struct BooleanTensor

Public Members

repeated bool value = 2: Flattened tensor of shape shape with C-like index order.

struct ByteTensor

Public Members

bytes value = 2: Flattened tensor of shape shape with C-like index order.

struct Int64Tensor

Public Members

repeated sint64 value = 2: Flattened tensor of shape shape with C-like index order.

struct FloatTensor

Public Members

repeated float value = 2: Flattened tensor of shape shape with C-like index order.

struct DoubleTensor

Public Members

repeated double value = 2: Flattened tensor of shape shape with C-like index order.

struct StringTensor

Public Members

repeated string value = 2: Flattened tensor of shape shape with C-like index order.

struct BooleanRange

The [min, max] range of a boolean scalar.

Public Members

oneof optional_min {bool min = 1: The minimum value (inclusive). If not set, the value is 0 (false).

oneof optional_max {bool max = 2: The maximum value (inclusive). If not set, the value is 1 (true).

struct Int64Range

The [min, max] range of an int64 scalar.

Public Members

oneof optional_min {sint64 min = 1: The minimum value (inclusive). If not set, the value is -2^63.

oneof optional_max {sint64 max = 2: The maximum value (inclusive). If not set, the value is 2^63 - 1.

struct FloatRange

The [min, max] range of an double scalar.

Public Members

oneof optional_min {float min = 1: The minimum value (inclusive). If not set, the value is -inf.

oneof optional_max {float max = 2: The maximum value (inclusive). If not set, the value is +inf.

struct DoubleRange

The [min, max] range of an double scalar.

Public Members

oneof optional_min {double min = 1: The minimum value (inclusive). If not set, the value is -inf.

oneof optional_max {double max = 2: The maximum value (inclusive). If not set, the value is +inf.

struct BooleanBox

struct ByteBox

struct Int64Box

struct FloatBox

struct DoubleBox

struct ListSpace: A list of spaces.

struct DictSpace

struct DiscreteSpace: A discrete space in :math:{ 0, 1, \\dots, n-1 };.

struct NamedDiscreteSpace

A discrete space in which every point in the space is named.

This can be used for representing enumerations.

Public Members

repeated string name = 1

A list of names for every value in the space.

The order in which these values are returned is used.

struct BooleanSequenceSpace

struct ByteSequenceSpace

struct BytesSequenceSpace

Public Members

Int64Range length_range = 1: Number of byte arrays in the sequence.

struct Int64SequenceSpace

struct FloatSequenceSpace

struct DoubleSequenceSpace

struct StringSequenceSpace

Public Members

Int64Range length_range = 1: The number of strings in the sequence.

struct SpaceSequenceSpace

A variable length sequence of spaces.

Public Members

Int64Range length_range = 1: The number of spaces in the sequence.

struct StringSpace

struct Opaque: Can be used in Space.any_value or Event.any_value to describe an opaque serialized data.

struct CommandlineSpace

struct ListEvent

struct DictEvent

struct Benchmark

Representation of the input to a compiler.

Public Members

string uri = 1

The name of the benchmark to add.

In case of conflict with an existing benchmark, this new benchmark replaces the existing one.

File program = 2

The description of the program that is being compiled.

It is up to the service to determine how to interpret this file, and it is the responsibility of the client to ensure that it provides the correct format. For example, the service could expect that this file contains serialized IR data, or an input source file.

BenchmarkDynamicConfig dynamic_config = 3: An optional configuration option that details how to build and run the benchmark program.

struct File

A File message represents a file object.

Public Members

string uri = 2

The URI of the file which can be accessed.

Note that this requires that the compiler service and the Python frontend share a file system, which cannot be assumed for general use.

struct BenchmarkDynamicConfig

Description of how to build and run a benchmark binary.

Public Members

Command build_cmd = 1: A command to execute to build the benchmark for dynamic execution.

Command run_cmd = 2: A command to execute to run the benchmark.

repeated Command pre_run_cmd = 3: A list of commands to execute before running the benchmark.

repeated Command post_run_cmd = 4: A list of commands to execute after running the benchmark.

struct Command

Representation of a command that can be executed.

Public Members

repeated string argument = 1: A list of command line arguments.

map<string, string> env = 2: An optional key-value mapping of environment variables to set.

int32 timeout_seconds = 3: The maximum runtime of the command.

repeated string infile = 4

An optional list of files that are required by this command.

If set, the presence of the files will be tested for before running the command. This can be useful for providing informative error messages.

repeated string outfile = 5

An optional list of files that are generated by this command.

If set, the presence of the files will be tested for after running the command.

struct SessionParameter

An arbitrary string parameter value for a session.

Public Members

string key = 1: A string key.

string value = 2: A string value.

RPC Service Reference

How it Works

CompilerGymService

Request and Reply Messages

Core Message Types

How it Works 

CompilerGymService 

Request and Reply Messages 

Core Message Types 