Merge pull request #281 from ChrisCummins/doxygen

Add C++ and protocol buffer API reference documentation

INSTALL.md

@@ -48,6 +48,7 @@ with the required dependencies:
 
     conda create -n compiler_gym python=3.9 cmake pandoc patchelf
     conda activate compiler_gym
+    conda install -c conda-forge doxygen
 
 Then clone the CompilerGym source code using:
 

Makefile

@@ -112,6 +112,7 @@ export HELP
 CC ?= clang
 CXX ?= clang++
 BAZEL ?= bazel
+DOXYGEN ?= doxygen
 IBAZEL ?= ibazel
 PANDOC ?= pandoc
 PYTHON ?= python3
@@ -196,13 +197,22 @@ GENERATED_DOCS := \
 
 gendocs: $(GENERATED_DOCS)
 
-docs: gendocs bazel-build
+doxygen:
+	cd docs && $(DOXYGEN) Doxyfile
+
+doxygen-rst:
+	cd docs && $(PYTHON) generate_cc_rst.py
+
+docs: gendocs bazel-build doxygen
 	PYTHONPATH=$(ROOT)/bazel-bin/package.runfiles/CompilerGym $(MAKE) -C docs html
 
-livedocs: gendocs
+livedocs: gendocs doxygen
 	PYTHONPATH=$(ROOT)/bazel-bin/package.runfiles/CompilerGym $(MAKE) -C docs livehtml
 
 
+.PHONY: doxygen doxygen-rst
+
+
 ###########
 # Testing #
 ###########

compiler_gym/service/proto/compiler_gym_service.proto

@@ -14,6 +14,8 @@ option java_multiple_files = true;
 option java_outer_classname = "CompilerGymServiceProto";
 option java_package = "com.compiler_gym";
 
+// The CompilerGymService is the interface that exposes the incremental
+// optimization of a program as an interactive environment.
 service CompilerGymService {
   // Request version strings from the service.
   rpc GetVersion(GetVersionRequest) returns (GetVersionReply);
@@ -43,21 +45,18 @@ service CompilerGymService {
   rpc AddBenchmark(AddBenchmarkRequest) returns (AddBenchmarkReply);
 }
 
-// ===========================================================================
-// GetVersion().
-
+// A GetVersion() request.
 message GetVersionRequest {}
 
+// The GetVersion() response.
 message GetVersionReply {
   // The version string for this service.
   string service_version = 1;
   // The version string for the underlying compiler.
   string compiler_version = 2;
 }
 
-// ===========================================================================
-// StartSession().
-
+// A StartSession() request.
 message StartSessionRequest {
   // The name of the benchmark to use for this session. If not provided, a
   // benchmark is chosen randomly by the service.
@@ -70,6 +69,7 @@ message StartSessionRequest {
   repeated int32 observation_space = 3;
 }
 
+// A StartSession() reply.
 message StartSessionReply {
   // 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.
@@ -86,9 +86,7 @@ message StartSessionReply {
   repeated Observation observation = 4;
 }
 
-// ===========================================================================
-// Step().
-
+// A Step() request.
 message StepRequest {
   // The ID of the session.
   int64 session_id = 1;
@@ -98,6 +96,7 @@ message StepRequest {
   repeated int32 observation_space = 3;
 }
 
+// A Step() reply.
 message StepReply {
   // 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
@@ -118,28 +117,27 @@ message StepReply {
   repeated Observation observation = 4;
 }
 
-// ===========================================================================
-// Actions.
-
+// A description of an action space.
+//
+// \warning This message format is likely to change. This currently only
+//     supports flat action spaces of categorical values. In the future we will
+//     want to replace this with a more extensible representation that supports
+//     parameterized actions, and actions of different types (e.g. optimization
+//     passes vs optimization contexts).
 message ActionSpace {
   // The name of the action space.
   string name = 1;
   // A list of discrete action names.
-  // NOTE(cummins): This currently only supports flat action spaces of
-  // categorical values. In the future we will want to replace this with a more
-  // extensible representation that supports parameterized actions, and actions
-  // of different types (e.g. optimization passes vs optimization contexts).
   repeated string action = 2;
 }
 
+// An action.
 message Action {
   // An index into the ActionSpace.action list.
   int32 action = 1;
 }
 
-// ===========================================================================
-// Observations.
-
+// An observations from a compiler.
 message Observation {
   // A point in an ObservationSpace is _either_ a scalar or vector of integers
   // or real values, a string, or an opaque byte array.
@@ -153,29 +151,35 @@ message Observation {
   }
 }
 
+// A list of 64 bit integers.
 message Int64List {
   repeated int64 value = 1;
 }
 
+// A list of doubles.
 message DoubleList {
   repeated double value = 1;
 }
 
+// The [min, max] range of a scalar.
 message ScalarRange {
   // The minimum value (inclusive). If not set, the value is -inf.
   ScalarLimit min = 1;
   // The maximum value (inclusive). If not set, the value is +inf.
   ScalarLimit max = 2;
 }
 
+// Representation of the upper or lower limit of a scalar.
 message ScalarLimit {
   double value = 1;
 }
 
+// A list of scalar ranges.
 message ScalarRangeList {
   repeated ScalarRange range = 1;
 }
 
+// The description of a space of observations.
 message ObservationSpace {
   // The name of the observation space.
   string name = 1;
@@ -211,37 +215,34 @@ message ObservationSpace {
   Observation default_value = 9;
 }
 
-// ===========================================================================
-// Fork().
-
+// A Fork() request.
 message ForkSessionRequest {
   // The ID of the session to fork.
   int64 session_id = 1;
 }
 
+// A Fork() reply.
 message ForkSessionReply {
   // The ID of the newly created session.
   int64 session_id = 1;
 }
 
-// ===========================================================================
-// EndSession().
-
+// An EndSession() request.
 message EndSessionRequest {
   // The ID of the session.
   int64 session_id = 1;
 }
 
+// An EndSession() reply.
 message EndSessionReply {
   // The number of sessions that the service currently has.
   int32 remaining_sessions = 1;
 }
 
-// ===========================================================================
-// GetSpaces().
-
+// A GetSpaces() request.
 message GetSpacesRequest {}
 
+// A GetSpaces() reply.
 message GetSpacesReply {
   // The initial space of actions. Subsequent calls to step() may produce
   // a new action space.
@@ -251,11 +252,7 @@ message GetSpacesReply {
   repeated ObservationSpace observation_space_list = 2;
 }
 
-// ===========================================================================
-// AddBenchmark().
-
-// A Benchmark message is used to register a new benchmark with a compiler
-// service.
+// Representation of the input to a compiler.
 message Benchmark {
   // The name of the benchmark to add. In case of conflict with an existing
   // benchmark, this new benchmark replaces the existing one.
@@ -278,8 +275,10 @@ message File {
   }
 }
 
+// An AddBenchmark() request.
 message AddBenchmarkRequest {
   repeated Benchmark benchmark = 1;
 }
 
+// An AddBenchmark() reply.
 message AddBenchmarkReply {}

compiler_gym/service/runtime/BenchmarkCache.h

@@ -18,31 +18,78 @@ namespace compiler_gym::runtime {
 
 constexpr size_t kEvictionSizeInBytes = 512 * 1024 * 1024;
 
-// An in-memory cache of Benchmark protocol buffers.
-//
-// 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%.
+/**
+ * @brief  A cache of Benchmark protocol 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%.
+ */
 class BenchmarkCache {
  public:
+  /**
+   * @brief Constructor.
+   *
+   * @param maxSizeInBytes The maximum size of the benchmark buffer before an
+   *    automated eviction is run.
+   * @param rand A random start used for selecting benchmarks for random
+   *    eviction.
+   */
   BenchmarkCache(size_t maxSizeInBytes = kEvictionSizeInBytes,
                  std::optional<std::mt19937_64> rand = std::nullopt);
 
-  // The pointer set by benchmark is valid only until the next call to add().
+  /**
+   * Lookup a benchmark. The pointer set by this method is valid only until the
+   * next call to add().
+   *
+   * @param uri The URI of the benchmark
+   * @return A Benchmark pointer.
+   */
   const Benchmark* get(const std::string& uri) const;
 
-  // Move-insert the given benchmark to the cache.
+  /**
+   * Move-insert the given benchmark to the cache.
+   *
+   * @param benchmark A benchmark to insert.
+   */
   void add(const Benchmark&& benchmark);
 
+  /**
+   * Get the number of elements in the cache.
+   *
+   * @return A nonnegative integer.
+   */
   inline size_t size() const { return benchmarks_.size(); };
+
+  /**
+   * Get the size of the cache in bytes.
+   *
+   * @return A nonnegative integer.
+   */
   inline size_t sizeInBytes() const { return sizeInBytes_; };
+
+  /**
+   * The maximum size of the cache before an eviction.
+   *
+   * @return A nonnegative integer.
+   */
   inline size_t maxSizeInBytes() const { return maxSizeInBytes_; };
 
+  /**
+   * Set a new maximum size of the cache.
+   *
+   * @param maxSizeInBytes A number of bytes.
+   */
   void setMaxSizeInBytes(size_t maxSizeInBytes);
 
-  // Evict benchmarks randomly to reduce the capacity to the given size. If
-  // targetSizeInBytes is not provided, benchmarks are evicted to 50% of
-  // maxSizeInBytes.
+  /**
+   * Evict benchmarks randomly to reduce the capacity to the given size.
+   *
+   * If `targetSizeInBytes` is not provided, benchmarks are evicted to 50% of
+   * `maxSizeInBytes`.
+   *
+   * @param targetSizeInBytes A target maximum size in bytes.
+   */
   void evictToCapacity(std::optional<size_t> targetSizeInBytes = std::nullopt);
 
  private: