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

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.

To use the service from C++, include the generated protocol buffer header:

#include "compiler_gym/service/proto/compiler_gym_service.pb.h"

To use the service from Python, import the generated protocol buffer module:

import compiler_gym.service.proto

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

The initial space of actions.

Subsequent calls to step() may produce a new action space.

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 Observation 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 Action 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 Observation observation   = 4

Observed states after completing the action.

struct AddBenchmarkRequest

An AddBenchmark() request.

struct AddBenchmarkReply

An AddBenchmark() reply.

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.