compiler_gym.service

CompilerGym uses a client/server architecture. Services provide an interface for manipulating compiler behavior. Clients are Python frontend objects that provide a reinforcement learning abstraction on top of the service. Communication between the service and client is done using RPC. The connection between the client and service is managed by the CompilerGymServiceConnection object.

class compiler_gym.service.CompilationSession(working_dir: pathlib.Path, action_space: compiler_gym.service.proto.compiler_gym_service_pb2.ActionSpace, benchmark: compiler_gym.service.proto.compiler_gym_service_pb2.Benchmark)[source]

Base class for encapsulating an incremental compilation session.

To add support for a new compiler, subclass from this base and provide implementations of the abstract methods, then call create_and_run_compiler_service and pass in your class type:

from compiler_gym.service import CompilationSession
from compiler_gym.service import runtime

class MyCompilationSession(CompilationSession):
    ...

if __name__ == "__main__":
    runtime.create_and_run_compiler_service(MyCompilationSession)
__init__(working_dir: pathlib.Path, action_space: compiler_gym.service.proto.compiler_gym_service_pb2.ActionSpace, benchmark: compiler_gym.service.proto.compiler_gym_service_pb2.Benchmark)[source]

Start a CompilationSession.

Subclasses should initialize the parent class first.

Parameters

  • working_dir – A directory on the local filesystem that can be used to store temporary files such as build artifacts.

  • action_space – The action space to use.

  • benchmark – The benchmark to use.

action_spaces: List[compiler_gym.service.proto.compiler_gym_service_pb2.ActionSpace] = []

A list of action spaces describing the capabilities of the compiler.

apply_action(action: compiler_gym.service.proto.compiler_gym_service_pb2.Action) → Tuple[bool, Optional[compiler_gym.service.proto.compiler_gym_service_pb2.ActionSpace], bool][source]

Apply an action.

Parameters

action – The action to apply.

Returns

A tuple: :code:`(end_of_session, new_action_space,

action_had_no_effect)`.

compiler_version: str = ''

The compiler version.

fork() → compiler_gym.service.compilation_session.CompilationSession[source]

Create a copy of current session state.

Implementing this method is optional.

Returns

A new CompilationSession with the same state.

get_observation(observation_space: compiler_gym.service.proto.compiler_gym_service_pb2.ObservationSpace) → compiler_gym.service.proto.compiler_gym_service_pb2.Observation[source]

Compute an observation.

Parameters

observation_space – The observation space.

Returns

An observation.

handle_session_parameter(key: str, value: str) → Optional[str][source]

Handle a session parameter send by the frontend.

Session parameters provide a method to send ad-hoc key-value messages to a compilation session through the env.send_session_parameter() method. It us up to the client/service to agree on a common schema for encoding and decoding these parameters.

Implementing this method is optional.

Parameters

  • key – The parameter key.

  • value – The parameter value.

Returns

A string response message if the parameter was understood. Else None to indicate that the message could not be interpretted.

observation_spaces: List[compiler_gym.service.proto.compiler_gym_service_pb2.ObservationSpace] = []

A list of feature vectors that this compiler provides.

The connection object

class compiler_gym.service.CompilerGymServiceConnection(endpoint: Union[str, pathlib.Path], opts: Optional[compiler_gym.service.connection.ConnectionOpts] = None, logger: Optional[logging.Logger] = None)[source]

A connection to a compiler gym service.

There are two types of service connections: managed and unmanaged. The type of connection is determined by the endpoint. If a “host:port” URL is provided, an unmanaged connection is created. If the path of a file is provided, a managed connection is used. The difference between a managed and unmanaged connection is that with a managed connection, the lifecycle of the service if controlled by the client connection. That is, when a managed connection is created, a service subprocess is started by executing the specified path. When the connection is closed, the subprocess is terminated. With an unmanaged connection, if the service fails is goes offline, the client will fail.

This class provides a common abstraction between the two types of connection, and provides a call method for invoking remote procedures on the service.

Example usage of an unmanaged service connection:

# Connect to a service running on localhost:8080. The user must
# started a process running on port 8080.
connection = CompilerGymServiceConnection("localhost:8080")
# Invoke an RPC method.
connection(connection.stub.StartSession, StartSessionRequest())
# Close the connection. The service running on port 8080 is
# left running.
connection.close()

Example usage of a managed service connection:

# Start a subprocess using the binary located at /path/to/my/service.
connection = CompilerGymServiceConnection(Path("/path/to/my/service"))
# Invoke an RPC method.
connection(connection.stub.StartSession, StartSessionRequest())
# Close the connection. The subprocess is terminated.
connection.close()
Variables

  • stub – A CompilerGymServiceStub that can be used as the first argument to __call__() to specify an RPC method to call.

  • action_spaces – A list of action spaces provided by the service.

  • observation_spaces – A list of observation spaces provided by the service.

__init__(endpoint: Union[str, pathlib.Path], opts: Optional[compiler_gym.service.connection.ConnectionOpts] = None, logger: Optional[logging.Logger] = None)[source]

Constructor.

Parameters

  • endpoint – The connection endpoint. Either the URL of a service, e.g. “localhost:8080”, or the path of a local service binary.

  • opts – The connection options.

Raises

  • ValueError – If the provided options are invalid.

  • FileNotFoundError – In case opts.local_service_binary is not found.

  • TimeoutError – In case the service failed to start within opts.init_max_seconds seconds.

__call__(stub_method: compiler_gym.service.connection.StubMethod, request: compiler_gym.service.connection.Request, timeout: Optional[float] = None, max_retries: Optional[int] = None, retry_wait_seconds: Optional[float] = None, retry_wait_backoff_exponent: Optional[float] = None) → compiler_gym.service.connection.Reply[source]

Invoke an RPC method on the service and return its response. All RPC methods accept a single request message, and respond with a response message.

Example usage:

connection = CompilerGymServiceConnection("localhost:8080")
request = compiler_gym.service.proto.GetSpacesRequest()
reply = connection(connection.stub.GetSpaces, request)

In the above example, the GetSpaces RPC method is invoked on a connection, yielding a GetSpacesReply message.

Parameters

  • stub_method – An RPC method attribute on CompilerGymServiceStub.

  • request – A request message.

  • timeout – The maximum number of seconds to await a reply. If not provided, the default value is ConnectionOpts.rpc_call_max_seconds.

  • max_retries – The maximum number of failed attempts to communicate with the RPC service before raising an error. Retries are made only for communication errors. Failures from other causes such as error signals raised by the service are not retried.

  • retry_wait_seconds – The number of seconds to wait between successive attempts to communicate with the RPC service.

  • retry_wait_backoff_exponent – The exponential backoff scaling between successive attempts to communicate with the RPC service.

Raises

  • ValueError – If the service responds with an error indicating an invalid argument.

  • NotImplementedError – If the service responds with an error indicating that the requested functionality is not implemented.

  • FileNotFoundError – If the service responds with an error indicating that a requested resource was not found.

  • OSError – If the service responds with an error indicating that it ran out of resources.

  • TypeError – If the provided request parameter is of incorrect type or cannot be serialized, or if the service responds with an error indicating that a precondition failed.

  • TimeoutError – If the service failed to respond to the query within the specified timeout.

  • ServiceTransportError – If the client failed to communicate with the service.

  • ServiceIsClosed – If the connection to the service is closed.

  • ServiceError – If the service raised an error not covered by any of the above conditions.

Returns

A reply message.

property closed: bool

Whether the connection is closed.

restart()[source]

Restart a connection a service. If the service is managed by this connection (i.e. it is a local binary), the existing service process will be killed and replaced. Else, only the connection to the unmanaged service process is replaced.

Configuring the connection

The ConnectionOpts object is used to configure the options used for managing a service connection.

class compiler_gym.service.ConnectionOpts(*, rpc_call_max_seconds: float = 300, rpc_max_retries: int = 5, retry_wait_seconds: float = 0.1, retry_wait_backoff_exponent: float = 1.5, init_max_seconds: float = 30, init_max_attempts: int = 5, local_service_port_init_max_seconds: float = 30, local_service_exit_max_seconds: float = 30, rpc_init_max_seconds: float = 3, always_send_benchmark_on_reset: bool = False, script_args: List[str] = [], script_env: Dict[str, str] = {})[source]

The options used to configure a connection to a service.

always_send_benchmark_on_reset: bool

Send the full benchmark program data to the compiler service on ever call to env.reset(). This is more efficient in cases where the majority of calls to env.reset() uses a different benchmark. In case of benchmark re-use, leave this False.

init_max_attempts: int

The maximum number of attempts to make to establish a connection to the service before failing.

init_max_seconds: float

The maximum number of seconds to spend attempting to establish a connection to the service before failing.

local_service_exit_max_seconds: float

The maximum number of seconds to wait for a local service to terminate on close.

local_service_port_init_max_seconds: float

The maximum number of seconds to wait for a local service to write the port.txt file.

retry_wait_backoff_exponent: float

The exponential backoff scaling between successive attempts to communicate with the RPC service.

retry_wait_seconds: float

The number of seconds to wait between successive attempts to communicate with the RPC service.

rpc_call_max_seconds: float

The maximum number of seconds to wait for an RPC method call to succeed.

rpc_init_max_seconds: float

The maximum number of seconds to wait for an RPC connection to establish.

rpc_max_retries: int

The maximum number of failed attempts to communicate with the RPC service before raising an error. Retries are made only for communication errors. Failures from other causes such as error signals raised by the service are not retried.

script_args: List[str]

If the service is started from a local script, this set of args is used on the command line. No effect when used for existing sockets.

script_env: Dict[str, str]

If the service is started from a local script, this set of env vars is used on the command line. No effect when used for existing sockets.

Exceptions

In general, errors raised by the service are converted to the equivalent builtin exception type, e.g., ValueError for invalid method arguments, and FileNotFound for resource errors. However, some error cases are not well covered by the builtin exception hierarchy. For those cases, we define custom exception types, all inheriting from a base ServiceError class:

exception compiler_gym.service.ServiceError[source]

Error raised from the service.

exception compiler_gym.service.EnvironmentNotSupported[source]

Error raised if the runtime requirements for an environment are not met on the current system.

exception compiler_gym.service.ServiceInitError[source]

Error raised if the service fails to initialize.

exception compiler_gym.service.ServiceTransportError[source]

Error that is raised if communication with the service fails.

exception compiler_gym.service.ServiceIsClosed[source]

Error that is raised if trying to interact with a closed service.

exception compiler_gym.service.SessionNotFound[source]

Requested session ID not found in service.