Merge PR #469: benchmark timing infrastructure (rebased from #343)

Adds opt-in benchmark timing infrastructure (6-timestamp struct t0..t6,
monotonic clock, JSON/CSV logging, thread-safe percentile stats collector,
extended device-metrics provider) plumbed through llm_component →
rac_llm_service → llamacpp backend + JNI so LLM inference can be timed
end-to-end with zero overhead when timing_out=NULL.

Conflict resolution: in llm_component.cpp's StreamingMetricsContext,
combined pr-472's cancel_flag pointer with pr-469's timing_out pointer —
both are orthogonal optional instrumentation hooks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sanchitmonga22

sdk/runanywhere-commons/CMakeLists.txt

@@ -393,6 +393,10 @@ set(RAC_CORE_SOURCES
     src/core/rac_core.cpp
     src/core/rac_error.cpp
     src/core/rac_time.cpp
+    src/core/rac_benchmark.cpp
+    src/core/rac_benchmark_metrics.cpp
+    src/core/rac_benchmark_log.cpp
+    src/core/rac_benchmark_stats.cpp
     src/core/rac_memory.cpp
     src/core/rac_logger.cpp
     src/core/rac_audio_utils.cpp

sdk/runanywhere-commons/include/rac/backends/rac_llm_llamacpp.h

@@ -11,6 +11,7 @@
 #ifndef RAC_LLM_LLAMACPP_H
 #define RAC_LLM_LLAMACPP_H
 
+#include "rac/core/rac_benchmark.h"
 #include "rac/core/rac_error.h"
 #include "rac/core/rac_types.h"
 #include "rac/features/llm/rac_llm.h"
@@ -163,6 +164,32 @@ RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_generate_stream(
     rac_handle_t handle, const char* prompt, const rac_llm_options_t* options,
     rac_llm_llamacpp_stream_callback_fn callback, void* user_data);
 
+/**
+ * Generates text with streaming callback and benchmark timing.
+ *
+ * Same as rac_llm_llamacpp_generate_stream but captures benchmark timing:
+ * - t2: Before prefill (llama_decode for prompt batch)
+ * - t3: After prefill completes
+ * - t5: When decode loop exits (last token)
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt text
+ * @param options Generation options
+ * @param callback Callback for each token
+ * @param user_data User context passed to callback
+ * @param timing_out Output: Benchmark timing struct, caller-allocated.
+ *                   Must remain valid for the duration of the call.
+ *                   Caller should initialize via rac_benchmark_timing_init() before passing.
+ *                   On success, all t2/t3/t5 fields are populated.
+ *                   On failure, status is set but timing fields may be partial.
+ *                   Pass NULL to skip timing (zero overhead).
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_generate_stream_with_timing(
+    rac_handle_t handle, const char* prompt, const rac_llm_options_t* options,
+    rac_llm_llamacpp_stream_callback_fn callback, void* user_data,
+    rac_benchmark_timing_t* timing_out);
+
 /**
  * Cancels ongoing generation.
  *

sdk/runanywhere-commons/include/rac/core/rac_benchmark.h

@@ -0,0 +1,136 @@
+/**
+ * @file rac_benchmark.h
+ * @brief RunAnywhere Commons - Benchmark Timing Support
+ *
+ * This header provides types and functions for benchmark timing instrumentation.
+ * The timing struct captures key timestamps during LLM inference for performance
+ * measurement and analysis.
+ *
+ * Design principles:
+ * - Zero overhead when not benchmarking: timing is opt-in via pointer parameter
+ * - Monotonic clock: uses steady_clock for accurate cross-platform timing
+ * - All timestamps are relative to a process-local epoch (not wall-clock)
+ */
+
+#ifndef RAC_BENCHMARK_H
+#define RAC_BENCHMARK_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// BENCHMARK TIMING STRUCT
+// =============================================================================
+
+/**
+ * Benchmark timing structure for LLM inference.
+ *
+ * Captures timestamps at key points during inference:
+ * - t0: Request start (component API entry)
+ * - t2: Prefill start (backend, before llama_decode for prompt)
+ * - t3: Prefill end (backend, after llama_decode returns)
+ * - t4: First token (component, first token callback)
+ * - t5: Last token (backend, decode loop exits)
+ * - t6: Request end (component, before complete callback)
+ *
+ * All timestamps are in milliseconds from a process-local epoch.
+ * Use rac_monotonic_now_ms() to get comparable timestamps.
+ *
+ * Note: t1 is intentionally skipped to match the specification.
+ */
+typedef struct rac_benchmark_timing {
+    /** t0: Request start - recorded at component API entry */
+    int64_t t0_request_start_ms;
+
+    /** t2: Prefill start - recorded before llama_decode for prompt batch */
+    int64_t t2_prefill_start_ms;
+
+    /** t3: Prefill end - recorded after llama_decode returns for prompt */
+    int64_t t3_prefill_end_ms;
+
+    /** t4: First token - recorded when first token callback is invoked */
+    int64_t t4_first_token_ms;
+
+    /** t5: Last token - recorded when decode loop exits */
+    int64_t t5_last_token_ms;
+
+    /** t6: Request end - recorded before complete callback */
+    int64_t t6_request_end_ms;
+
+    /** Number of tokens in the prompt */
+    int32_t prompt_tokens;
+
+    /** Number of tokens generated */
+    int32_t output_tokens;
+
+    /**
+     * Status of the benchmark request.
+     * Uses RAC_BENCHMARK_STATUS_* codes:
+     * - RAC_BENCHMARK_STATUS_SUCCESS (0): Completed successfully
+     * - RAC_BENCHMARK_STATUS_ERROR (1): Failed
+     * - RAC_BENCHMARK_STATUS_TIMEOUT (2): Timed out
+     * - RAC_BENCHMARK_STATUS_CANCELLED (3): Cancelled
+     */
+    int32_t status;
+
+    /**
+     * Specific error code when status is not RAC_BENCHMARK_STATUS_SUCCESS.
+     * Uses rac_result_t error codes (e.g., RAC_ERROR_NOT_SUPPORTED).
+     * Set to RAC_SUCCESS (0) when status is RAC_BENCHMARK_STATUS_SUCCESS.
+     */
+    rac_result_t error_code;
+
+} rac_benchmark_timing_t;
+
+// =============================================================================
+// BENCHMARK STATUS CODES
+// =============================================================================
+
+/** Benchmark request completed successfully */
+#define RAC_BENCHMARK_STATUS_SUCCESS ((int32_t)0)
+
+/** Benchmark request failed due to error */
+#define RAC_BENCHMARK_STATUS_ERROR ((int32_t)1)
+
+/** Benchmark request timed out */
+#define RAC_BENCHMARK_STATUS_TIMEOUT ((int32_t)2)
+
+/** Benchmark request was cancelled */
+#define RAC_BENCHMARK_STATUS_CANCELLED ((int32_t)3)
+
+// =============================================================================
+// MONOTONIC TIME API
+// =============================================================================
+
+/**
+ * Gets the current monotonic time in milliseconds.
+ *
+ * Uses std::chrono::steady_clock for accurate, monotonic timing that is not
+ * affected by system clock changes. The returned value is relative to a
+ * process-local epoch (the first call to this function).
+ *
+ * This function is thread-safe and lock-free on all supported platforms.
+ *
+ * @return Current monotonic time in milliseconds from process-local epoch
+ */
+RAC_API int64_t rac_monotonic_now_ms(void);
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Initializes a benchmark timing struct to zero values.
+ *
+ * @param timing Pointer to timing struct to initialize
+ */
+RAC_API void rac_benchmark_timing_init(rac_benchmark_timing_t* timing);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_BENCHMARK_H */

sdk/runanywhere-commons/include/rac/core/rac_benchmark_log.h

@@ -0,0 +1,119 @@
+/**
+ * @file rac_benchmark_log.h
+ * @brief RunAnywhere Commons - Benchmark Logging and Serialization
+ *
+ * Provides functions to serialize benchmark timing data as JSON or CSV,
+ * and to log benchmark results via the RAC logging system.
+ *
+ * All functions return rac_result_t for consistent error handling.
+ * Serialization functions write a heap-allocated string to an out-parameter
+ * (caller must free() on success).
+ *
+ * Usage:
+ *   // Log timing summary
+ *   rac_benchmark_timing_log(&timing, "inference_run_1");
+ *
+ *   // Export as JSON
+ *   char* json = NULL;
+ *   if (rac_benchmark_timing_to_json(&timing, &json) == RAC_SUCCESS) {
+ *       // ... use json ...
+ *       free(json);
+ *   }
+ *
+ *   // Export as CSV
+ *   char* header = NULL;
+ *   char* row = NULL;
+ *   rac_benchmark_timing_to_csv(NULL, RAC_TRUE, &header);
+ *   rac_benchmark_timing_to_csv(&timing, RAC_FALSE, &row);
+ *   free(header);
+ *   free(row);
+ */
+
+#ifndef RAC_BENCHMARK_LOG_H
+#define RAC_BENCHMARK_LOG_H
+
+#include "rac/core/rac_benchmark.h"
+#include "rac/core/rac_error.h"
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// JSON SERIALIZATION
+// =============================================================================
+
+/**
+ * Serializes a benchmark timing struct as a JSON string.
+ *
+ * Includes all timing fields plus derived metrics:
+ * - ttft_ms: Time to first token (t4 - t0)
+ * - prefill_ms: Prefill duration (t3 - t2)
+ * - decode_ms: Decode duration (t5 - t3)
+ * - e2e_ms: End-to-end latency (t6 - t0)
+ * - decode_tps: Decode throughput (output_tokens / decode_ms * 1000)
+ *
+ * On success, *out_json is set to a heap-allocated string that the caller
+ * must release via free(). On failure, *out_json is set to NULL.
+ *
+ * @param timing   Timing struct to serialize (must not be NULL)
+ * @param out_json Output pointer that receives the JSON string (must not be NULL)
+ * @return RAC_SUCCESS on success,
+ *         RAC_ERROR_NULL_POINTER if timing or out_json is NULL,
+ *         RAC_ERROR_OUT_OF_MEMORY if allocation fails
+ */
+RAC_API rac_result_t rac_benchmark_timing_to_json(const rac_benchmark_timing_t* timing,
+                                                  char** out_json);
+
+// =============================================================================
+// CSV SERIALIZATION
+// =============================================================================
+
+/**
+ * Serializes a benchmark timing struct as a CSV row.
+ *
+ * When header is RAC_TRUE, emits the CSV header row (timing may be NULL).
+ * When header is RAC_FALSE, emits a data row (timing must not be NULL).
+ *
+ * On success, *out_csv is set to a heap-allocated string that the caller
+ * must release via free(). On failure, *out_csv is set to NULL.
+ *
+ * @param timing  Timing struct to serialize (ignored when header is RAC_TRUE,
+ *                otherwise must not be NULL)
+ * @param header  If RAC_TRUE, emits the CSV header row instead of data
+ * @param out_csv Output pointer that receives the CSV string (must not be NULL)
+ * @return RAC_SUCCESS on success,
+ *         RAC_ERROR_NULL_POINTER if out_csv is NULL, or if header is RAC_FALSE
+ *             and timing is NULL,
+ *         RAC_ERROR_OUT_OF_MEMORY if allocation fails
+ */
+RAC_API rac_result_t rac_benchmark_timing_to_csv(const rac_benchmark_timing_t* timing,
+                                                 rac_bool_t header,
+                                                 char** out_csv);
+
+// =============================================================================
+// LOGGING
+// =============================================================================
+
+/**
+ * Logs a benchmark timing summary via the RAC logging system.
+ *
+ * Outputs key metrics at INFO level under the "Benchmark" category:
+ * - TTFT, prefill time, decode time, E2E latency
+ * - Token counts and throughput
+ * - Status and error code
+ *
+ * @param timing Timing struct to log (must not be NULL)
+ * @param label  Optional label for this benchmark run (may be NULL)
+ * @return RAC_SUCCESS on success,
+ *         RAC_ERROR_NULL_POINTER if timing is NULL
+ */
+RAC_API rac_result_t rac_benchmark_timing_log(const rac_benchmark_timing_t* timing,
+                                              const char* label);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_BENCHMARK_LOG_H */