[Caching] Add new CacheReplay APIs to libSwiftScan

Add new APIs libSwiftScan that can be used for cache query and cache
replay. This enables swift-driver or build system to query the cache and
replay the compilation results without invocation swift-frontend for
better scheduling.

Author: cachemeifyoucan

include/swift-c/DependencyScan/DependencyScan.h

@@ -25,7 +25,7 @@
 /// SWIFTSCAN_VERSION_MINOR should increase when there are API additions.
 /// SWIFTSCAN_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
 #define SWIFTSCAN_VERSION_MAJOR 0
-#define SWIFTSCAN_VERSION_MINOR 5
+#define SWIFTSCAN_VERSION_MINOR 6
 
 SWIFTSCAN_BEGIN_DECLS
 
@@ -441,6 +441,53 @@ typedef struct swiftscan_cas_options_s *swiftscan_cas_options_t;
 /// ActionCache.
 typedef struct swiftscan_cas_s *swiftscan_cas_t;
 
+/// Opaque container for a cached compilation.
+typedef struct swiftscan_cached_compilation_s *swiftscan_cached_compilation_t;
+
+/// Opaque container for a cached compilation output.
+typedef struct swiftscan_cached_output_s *swiftscan_cached_output_t;
+
+/// Opaque type for a cache replay instance.
+typedef struct swiftscan_cache_replay_instance_s
+    *swiftscan_cache_replay_instance_t;
+
+/// Opaque container for a cached compilation replay result.
+typedef struct swiftscan_cache_replay_result_s
+    *swiftscan_cache_replay_result_t;
+
+/// Opaque type for a cancellation token for async cache operations.
+typedef struct swiftscan_cache_cancellation_token_s
+    *swiftscan_cache_cancellation_token_t;
+
+/// Enum types for output types for cache key computation.
+/// List should contain all the output file types, including supplemententary
+/// outputs, except diagnostics outputs, which are covered by cached diagnostic
+/// entry.
+typedef enum {
+  SWIFTSCAN_OUTPUT_TYPE_OBJECT = 0,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFTMODULE = 1,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFTINTERFACE = 2,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFTPRIVATEINTERFACE = 3,
+  SWIFTSCAN_OUTPUT_TYPE_CLANG_MODULE = 4,
+  SWIFTSCAN_OUTPUT_TYPE_CLANG_PCH = 5,
+  SWIFTSCAN_OUTPUT_TYPE_CLANG_HEADER = 6,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_SOURCE_INFO = 7,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_MODULE_DOC = 8,
+  SWIFTSCAN_OUTPUT_TYPE_DEPENDENCIES = 9,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_DEPS = 10,
+  SWIFTSCAN_OUTPUT_TYPE_MODULE_TRACE = 11,
+  SWIFTSCAN_OUTPUT_TYPE_TBD = 12,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_MODULE_SUMMARY = 13,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_ABI_DESCRIPTOR = 14,
+  SWIFTSCAN_OUTPUT_TYPE_SWIFT_API_DESCRIPTOR = 15,
+  SWIFTSCAN_OUTPUT_TYPE_CONST_VALUE = 16,
+  SWIFTSCAN_OUTPUT_TYPE_MODULE_SEMANTIC_INFO = 17,
+  SWIFTSCAN_OUTPUT_TYPE_YAML_OPT_RECORD = 18,
+  SWIFTSCAN_OUTPUT_TYPE_BITSTREAM_OPT_RECORD = 19,
+  SWIFTSCAN_OUTPUT_TYPE_CACHED_DIAGNOSTICS = 20,
+  SWIFTSCAN_OUTPUT_TYPE_LAST = SWIFTSCAN_OUTPUT_TYPE_CACHED_DIAGNOSTICS
+} swiftscan_output_kind_t;
+
 /// Create a \c CASOptions for creating CAS inside scanner specified.
 SWIFTSCAN_PUBLIC swiftscan_cas_options_t swiftscan_cas_options_create(void);
 
@@ -472,16 +519,16 @@ swiftscan_cas_options_set_option(swiftscan_cas_options_t options,
 SWIFTSCAN_PUBLIC swiftscan_cas_t swiftscan_cas_create_from_options(
     swiftscan_cas_options_t options, swiftscan_string_ref_t *error);
 
-/// Dispose the \c cas instance.
-SWIFTSCAN_PUBLIC void swiftscan_cas_dispose(swiftscan_cas_t cas);
-
 /// Store content into CAS. Return \c CASID as string. Return NULL on error.
 /// If error happens, the error message is returned via `error` parameter, and
 /// caller needs to free the error message via `swiftscan_string_dispose`.
 SWIFTSCAN_PUBLIC swiftscan_string_ref_t
 swiftscan_cas_store(swiftscan_cas_t cas, uint8_t *data, unsigned size,
                     swiftscan_string_ref_t *error);
 
+/// Dispose the \c cas instance.
+SWIFTSCAN_PUBLIC void swiftscan_cas_dispose(swiftscan_cas_t cas);
+
 /// Compute \c CacheKey for the outputs of a primary input file from a compiler
 /// invocation with command-line \c argc and \c argv. When primary input file
 /// is not available for compilation, e.g., using WMO, primary file is the first
@@ -492,6 +539,151 @@ SWIFTSCAN_PUBLIC swiftscan_string_ref_t
 swiftscan_cache_compute_key(swiftscan_cas_t cas, int argc, const char **argv,
                             const char *input, swiftscan_string_ref_t *error);
 
+/// Query the result of the compilation using the output cache key. \c globally
+/// suggests if the lookup should check remote cache if such operation exists.
+/// Returns the cached compilation of the result if found, or nullptr if output
+/// is not found or an error occurs. When an error occurs, the error message is
+/// returned via \c error parameter and its caller needs to free the message
+/// using `swiftscan_string_dispose`. The returned cached compilation needs to
+/// be freed via `swiftscan_cached_compilation_dispose`.
+SWIFTSCAN_PUBLIC swiftscan_cached_compilation_t
+swiftscan_cache_query(swiftscan_cas_t cas, const char *key, bool globally,
+                      swiftscan_string_ref_t *error);
+
+/// Async version of `swiftscan_cache_query` where result is returned via
+/// callback. Both cache_result enum and cached compilation will be provided to
+/// callback. \c ctx is an opaque value that passed to the callback and \c
+/// swiftscan_cache_cancellation_token_t will return an token that can be used
+/// to cancel the async operation. The token needs to be freed by caller using
+/// `swiftscan_cache_cancellation_token_dispose`.
+SWIFTSCAN_PUBLIC void swiftscan_cache_query_async(
+    swiftscan_cas_t cas, const char *key, bool globally, void *ctx,
+    void (*callback)(void *ctx, swiftscan_cached_compilation_t,
+                     swiftscan_string_ref_t error),
+    swiftscan_cache_cancellation_token_t *);
+
+/// Query the number of outputs from a cached compilation.
+SWIFTSCAN_PUBLIC unsigned swiftscan_cached_compilation_get_num_outputs(
+    swiftscan_cached_compilation_t);
+
+/// Get the output kind for the given index in the cached compilation.
+SWIFTSCAN_PUBLIC swiftscan_output_kind_t
+swiftscan_cached_compilation_get_output_kind(swiftscan_cached_compilation_t,
+                                             unsigned idx);
+
+/// Get the cached output for the given index in the cached compilation.
+SWIFTSCAN_PUBLIC swiftscan_cached_output_t
+swiftscan_cached_compilation_get_output(swiftscan_cached_compilation_t,
+                                        unsigned idx);
+
+/// Make the cache compilation available globally. \c callback will be called
+/// on completion.
+/// \c swiftscan_cache_cancellation_token_t will return an token that can be
+/// used to cancel the async operation. The token needs to be freed by caller
+/// using `swiftscan_cache_cancellation_token_dispose`.
+SWIFTSCAN_PUBLIC void swiftscan_cached_compilation_make_global_async(
+    swiftscan_cas_t cas, swiftscan_cached_compilation_t, void *ctx,
+    void (*callback)(void *ctx, swiftscan_string_ref_t error),
+    swiftscan_cache_cancellation_token_t *);
+
+/// Dispose a cached compilation.
+SWIFTSCAN_PUBLIC
+void swiftscan_cached_compilation_dispose(swiftscan_cached_compilation_t);
+
+/// Download and materialize the cached output if needed from a remote CAS.
+/// Return true if load is successful, else false if not found or error. If
+/// error, the error message is returned via \c error parameter and its caller
+/// needs to free the message using `swiftscan_string_dispose`.
+SWIFTSCAN_PUBLIC bool
+swiftscan_cached_output_load(swiftscan_cas_t cas, swiftscan_cached_output_t,
+                             swiftscan_string_ref_t *error);
+
+/// Async version of `swiftscan_cached_output_load` where result is
+/// returned via callback. \c ctx is an opaque value that passed to the callback
+/// and \c swiftscan_cache_cancellation_token_t will return an token that can be
+/// used to cancel the async operation. The token needs to be freed by caller
+/// using `swiftscan_cache_cancellation_token_dispose`.
+SWIFTSCAN_PUBLIC void swiftscan_cached_output_load_async(
+    swiftscan_cas_t cas, swiftscan_cached_output_t, void *ctx,
+    void (*callback)(void *ctx, bool success, swiftscan_string_ref_t error),
+    swiftscan_cache_cancellation_token_t *);
+
+/// Check if cached output is materialized locally and can be accessed
+/// without downloading.
+SWIFTSCAN_PUBLIC bool
+    swiftscan_cached_output_is_materialized(swiftscan_cas_t,
+                                            swiftscan_cached_output_t);
+
+/// Dispose a cached output.
+SWIFTSCAN_PUBLIC
+void swiftscan_cached_output_dispose(swiftscan_cached_output_t);
+
+/// Cancel the async cache action that is associated with token.
+SWIFTSCAN_PUBLIC void
+    swiftscan_cache_action_cancel(swiftscan_cache_cancellation_token_t);
+
+/// Dispose the cancellation token.
+SWIFTSCAN_PUBLIC void swiftscan_cache_cancellation_token_dispose(
+    swiftscan_cache_cancellation_token_t);
+
+/// Create a swift cached compilation replay instance with its command-line
+/// invocation. Return nullptr when errors occurs and the error message is
+/// returned via \c error parameter and its caller needs to free the message
+/// using `swiftscan_string_dispose`.
+SWIFTSCAN_PUBLIC swiftscan_cache_replay_instance_t
+swiftscan_cache_replay_instance_create(int argc, const char **argv,
+                                       swiftscan_string_ref_t *error);
+
+/// Dispose swift cached compilation replay instance.
+SWIFTSCAN_PUBLIC void
+    swiftscan_cache_replay_instance_dispose(swiftscan_cache_replay_instance_t);
+
+/// Replay the cached compilation using cached compliation replay instance.
+/// Returns replay result or nullptr if output not found or error occurs. If
+/// error, the error message is returned via \c error parameter and its caller
+/// needs to free the message using `swiftscan_string_dispose`.
+SWIFTSCAN_PUBLIC swiftscan_cache_replay_result_t
+swiftscan_cache_replay_compilation(swiftscan_cas_t cas,
+                                   swiftscan_cache_replay_instance_t,
+                                   swiftscan_cached_compilation_t,
+                                   swiftscan_string_ref_t *error);
+
+/// Async replay the cached compilation. Callback function will be provided
+/// by the cache replay result, and its stdout, stderr, and any error message.
+/// \c ctx is an opaque value that passed to the callback and
+/// \c swiftscan_cache_cancellation_token_t will return an token that can be
+/// used to cancel the async operation. The token needs to be freed by caller
+/// using `swiftscan_cache_cancellation_token_dispose`.
+SWIFTSCAN_PUBLIC void swiftscan_cache_replay_compilation_async(
+    swiftscan_cas_t cas, swiftscan_cache_replay_instance_t,
+    swiftscan_cached_compilation_t, void *ctx,
+    void (*callback)(void *ctx, swiftscan_cache_replay_result_t,
+                     swiftscan_string_ref_t error),
+    swiftscan_cache_cancellation_token_t *);
+
+/// Get return code from replay. Return code is 0 for success, and a non-zero
+/// value for failure.
+/// FIXME: This should match the return code from `swift-frontend` invocation.
+SWIFTSCAN_PUBLIC
+unsigned swiftscan_cache_replay_result_get_return_code(
+    swiftscan_cache_replay_result_t);
+
+/// Get stdout from cached replay result. The returning swiftscan_string_ref_t
+/// is owned by replay result and should not be disposed.
+SWIFTSCAN_PUBLIC
+swiftscan_string_ref_t
+    swiftscan_cache_replay_result_get_stdout(swiftscan_cache_replay_result_t);
+
+/// Get stderr from cached replay result. The returning swiftscan_string_ref_t
+/// is owned by replay result and should not be disposed.
+SWIFTSCAN_PUBLIC
+swiftscan_string_ref_t
+    swiftscan_cache_replay_result_get_stderr(swiftscan_cache_replay_result_t);
+
+/// Dispose a cached replay result.
+SWIFTSCAN_PUBLIC
+void swiftscan_cache_replay_result_dispose(swiftscan_cache_replay_result_t);
+
 //===----------------------------------------------------------------------===//
 
 SWIFTSCAN_END_DECLS

test/CAS/swift-scan-test.swift

@@ -0,0 +1,24 @@
+// RUN: %empty-directory(%t)
+
+// RUN: %swift-scan-test -action compute_cache_key -cas-path %t/cas -input %s -- %target-swift-frontend -cache-compile-job -Rcache-compile-job %s \
+// RUN:   -emit-module -emit-module-path %t/Test.swiftmodule -c -emit-dependencies -module-name Test -o %t/test.o -cas-path %t/cas \
+// RUN:   -allow-unstable-cache-key-for-testing > %t/key.casid
+
+// RUN: not %swift-scan-test -action cache_query -id @%t/key.casid -cas-path %t/cas 2>&1 | %FileCheck %s --check-prefix=CHECK-QUERY-NOT-FOUND
+
+// RUN: %target-swift-frontend -cache-compile-job -Rcache-compile-job %s -emit-module -emit-module-path %t/Test.swiftmodule -c -emit-dependencies \
+// RUN:  -module-name Test -o %t/test.o -cas-path %t/cas -allow-unstable-cache-key-for-testing
+
+// RUN: %swift-scan-test -action cache_query -id @%t/key.casid -cas-path %t/cas | %FileCheck %s --check-prefix=CHECK-QUERY
+
+// RUN: %swift-scan-test -action replay_result -cas-path %t/cas -id @%t/key.casid -- %target-swift-frontend -cache-compile-job -Rcache-compile-job %s \
+// RUN:   -emit-module -emit-module-path %t/Test2.swiftmodule -c -emit-dependencies -module-name Test -o %t/test2.o -cas-path %t/cas \
+// RUN:   -allow-unstable-cache-key-for-testing
+
+// RUN: diff %t/Test.swiftmodule %t/Test2.swiftmodule
+// RUN: diff %t/test.o %t/test.o
+
+// CHECK-QUERY-NOT-FOUND: cached output not found
+// CHECK-QUERY: Cached Compilation for key "llvmcas://{{.*}}" has 4 outputs: (object) (dependencies) (swiftmodule) (cached-diagnostics)
+
+func testFunc() {}

test/lit.cfg

@@ -346,6 +346,7 @@ config.benchmark_driver = inferSwiftBinary('Benchmark_Driver')
 config.wasm_ld = inferSwiftBinary('wasm-ld')
 config.swift_plugin_server = inferSwiftBinary('swift-plugin-server')
 config.swift_parse_test = inferSwiftBinary('swift-parse-test')
+config.swift_scan_test = inferSwiftBinary('swift-scan-test')
 
 config.swift_utils = make_path(config.swift_src_root, 'utils')
 config.line_directive = make_path(config.swift_utils, 'line-directive')
@@ -638,6 +639,7 @@ config.substitutions.append( ('%target-ptrauth', run_ptrauth ) )
 config.substitutions.append( ('%swift-path', config.swift) )
 config.substitutions.append( ('%swift-plugin-server', config.swift_plugin_server) )
 config.substitutions.append( ('%swift-parse-test', config.swift_parse_test) )
+config.substitutions.append( ('%swift-scan-test', config.swift_scan_test) )
 config.substitutions.append( ('%validate-json', f"{config.python} -m json.tool") )
 
 # This must come after all substitutions containing "%swift".

tools/CMakeLists.txt

@@ -28,6 +28,7 @@ add_swift_tool_subdirectory(libSwiftScan)
 add_swift_tool_subdirectory(libStaticMirror)
 add_swift_tool_subdirectory(libMockPlugin)
 add_swift_tool_subdirectory(swift-plugin-server)
+add_swift_tool_subdirectory(swift-scan-test)
 
 if(SWIFT_INCLUDE_TESTS OR SWIFT_INCLUDE_TEST_BINARIES)
   add_swift_tool_subdirectory(swift-ide-test)

tools/libSwiftScan/CMakeLists.txt

@@ -7,6 +7,7 @@ set(LLVM_EXPORTED_SYMBOL_FILE
 add_swift_host_library(libSwiftScan SHARED
   libSwiftScan.cpp
   c-include-check.c
+  SwiftCaching.cpp
   HAS_SWIFT_MODULES)
 
 if(SWIFT_HOST_VARIANT_SDK IN_LIST SWIFT_DARWIN_PLATFORMS)