Time Library User Manual

User Manual Time Library Component		status: draft security: NO safety: QM
version: 1 realizes: wp__training_path
doc__user_manual_time_lib		Generic Document

Overview

This user manual covers the score::time client library - the C++ API for accessing synchronized time in your applications.

The library provides multiple clock types (VehicleTime, SystemTime, SteadyTime, HighResSteadyTime) with a unified interface for time access, lifecycle management, and testing.

For module-level integration and deployment information, see the main module manual.

Choosing the Right Clock

The S-CORE time module provides several clock types, each designed for a specific use case. Understanding their differences is crucial for writing robust and correct applications.

In general, you should always prefer ``VehicleTime`` unless you have a specific reason to measure a local time interval or need a simple wall-clock timestamp for purely informational purposes.

Table 12 Clock Types Overview

Clock Type	Key Characteristic	Typical Use Case
VehicleTime	High-precision, PTP-synchronized, quality-assured network time. This is the recommended clock for almost all applications.	Synchronized logging across ECUs, event timestamping, any logic that depends on a common time base in the vehicle.
SystemTime	The system’s “wall clock” time (Unix time). Can jump forwards or backwards (e.g., due to NTP correction or manual changes).	Displaying human-readable timestamps. Creating log entries where absolute time is more important than monotonic progression.
SteadyTime	A clock that is guaranteed to only ever move forward (monotonic). Its starting point is arbitrary (e.g., system boot time).	Measuring time intervals, implementing timeouts, scheduling tasks where guaranteed monotonic progression is essential.
HighResSteadyTime	A monotonic clock that provides the highest possible resolution the underlying hardware can offer.	High-precision performance measurements and profiling, or very short-interval timing.

API Usage

This section covers how to use the score::time client library in your applications:

• API Usage: Accessing Vehicle Time
  • Polling the Current Time
• Clock Lifecycle Management
  • Initializing the Clock
  • Waiting for Availability
  • Checking Availability (Non-Blocking)
• Unit-Testing Time-Dependent Code
• A Helper for Controllable Time: The ClockTestFactory
• Example: Testing a Timeout Handler
• Bazel BUILD Setup
• Advanced API Usage: Subscribing to PTP Protocol Events
  • Available Data Subscriptions
  • Subscribing to Events
  • Threading and Safety Considerations
  • Unsubscribing

Note

For a complete C++ API reference with full class and function documentation, please refer to the generated Doxygen documentation (to be added in future releases).

Examples

Practical examples and tutorials for using the time library:

• Examples User Manual
  • Overview
  • Building and Running Examples
  • Common Patterns

Build Integration

To use the score::time library in your application:

1. Add the module to your Bazel workspace:

   # In your MODULE.bazel
   bazel_dep(name = "score_time", version = "1.0")
   

2. Reference the clock type you need in your build files:

   cc_library(
       name = "my_target",
       deps = [
           "@score_time//score/time/vehicle_time:vehicle_time",  # For VehicleTime
           # OR
           "@score_time//score/time/system_time:system_time",     # For SystemTime
           # OR
           "@score_time//score/time/steady_time:steady_time",     # For SteadyTime
           # OR
           "@score_time//score/time/high_res_steady_time:high_res_steady_time",  # For HighResSteadyTime
       ],
   )
   

   For testing, use the mock variants:

   cc_test(
       name = "my_test",
       deps = [
           "@score_time//score/time/vehicle_time:vehicle_time_mock",
       ],
   )
   

3. Include headers in your code:

   #include "score/time/clock.h"
   #include "score/time/vehicle_time.h"
   
   // Example usage
   auto& clock = score::time::Clock<score::time::VehicleTime>::GetInstance();
   auto snapshot = clock.Now();
   if (snapshot.Status().IsReliable()) {
       // Use snapshot.TimePoint()
   }
   

Runtime Requirements

The score::time library requires the TimeSlave and TimeDaemon system services to be running. For deployment and configuration of these services, refer to the module manual and component manuals for Time Slave User Manual and Time Daemon User Manual.