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.

Common Runtime

compiler_gym.service.runtime.create_and_run_compiler_gym_service(compilation_session_type: Type[CompilationSession])[source]

Create and run an RPC service for the given compilation session.

This should be called on its own in a self contained script to implement a compilation service. Example:

from compiler_gym.service import runtime
from my_compiler_service import MyCompilationSession

if __name__ == "__main__":

This function never returns.


compilation_session_type – A sublass of CompilationSession that provides implementations of the abstract methods.


class compiler_gym.service.runtime.compiler_gym_service.CompilerGymService(working_directory: Path, compilation_session_type)[source]
__init__(working_directory: Path, compilation_session_type)[source]


  • working_directory – The working directory for this service.

  • compilation_session_type – The CompilationSession type that this service implements.

AddBenchmark(request: AddBenchmarkRequest, context) AddBenchmarkReply[source]

Register a new benchmark.

EndSession(request: EndSessionRequest, context) EndSessionReply[source]

End a CompilerGym service session. If the requested session does not exist, this returns an error.

ForkSession(request: ForkSessionRequest, context) ForkSessionReply[source]

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.

GetSpaces(request: GetSpacesRequest, context) GetSpacesReply[source]

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.

GetVersion(request: GetVersionRequest, context) GetVersionReply[source]

Request version strings from the service.

SendSessionParameter(request: SendSessionParameterRequest, context) SendSessionParameterReply[source]

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.

StartSession(request: StartSessionRequest, context) StartSessionReply[source]

Create a new compilation session.

Step(request: StepRequest, context) StepReply[source]

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.


class compiler_gym.service.runtime.benchmark_cache.BenchmarkCache(max_size_in_bytes: int = 54525952, rng: Optional[Generator] = None)[source]

An in-memory cache of Benchmark messages.

This object caches Benchmark messages by URI. Once the cache reaches a predetermined size, benchmarks are evicted randomly until the capacity is reduced to 50%.

__init__(max_size_in_bytes: int = 54525952, rng: Optional[Generator] = None)[source]
evict_to_capacity(target_size_in_bytes: Optional[int] = None) None[source]

Evict benchmarks randomly to reduce the capacity below 50%.

property max_size_in_bytes: int

The maximum size of the cache.

property size: int

The number of items in the cache.

property size_in_bytes: int

The combined size of the elements in the cache, excluding the cache overhead.