[trace] Add `SBTraceCursor::GetWallClockTime` API

[jj10306]

Summary

WIP

[jj10306]

lldb/source/API/SBTraceCursor.cpp

131

open to suggestions on the best way to indicate that the current item doesn't have a timestamp associated with it

[hawkinsw]

lldb/source/API/SBTraceCursor.cpp

131

Could we use llvm::Optional? Sorry if that is a silly suggestion.

[wallace]

lldb/include/lldb/API/SBTraceCursor.h

175

mention here that the trace plugin decides how to estimate wall clock time it needed, and that not all trace items are guaranteed to have wall clock time, as it depends on the trace plug-in capabilities

lldb/source/API/SBTraceCursor.cpp

127–131

we don't have optionals in the SB bridge, so you could do the following

bool SBTraceCursor::GetWallClockTime(double &time) {
  if (const auto &maybe_wall_clock_time = m_opaque_sp->GetWallClockTime()) {
    time = *maybe_wall_clock_time;
    return true;
  }
  return false;
}

[hawkinsw]

lldb/source/API/SBTraceCursor.cpp

127–131

Not that it matters, but *that* was going to be my other suggestion! @wallace is smarter than I am!

[jj10306]

update the way items with no timestamps are handled

[wallace]

lldb/source/API/SBTraceCursor.cpp

127–131

<3

lldb/bindings/interface/SBTraceCursor.i

public:
   const char *GetEventTypeAsString() const;
 
   bool IsInstruction() const;
 
   lldb::addr_t GetLoadAddress() const;
 
   lldb::cpu_id_t GetCPU() const;
 
+  bool GetWallClockTime(double &estimated_time) const;
+
   bool IsValid() const;
 
   explicit operator bool() const;
 };
 } // namespace lldb

lldb/include/lldb/API/SBTraceCursor.h

public:
   ///     The load address of the instruction the cursor is pointing at.
   lldb::addr_t GetLoadAddress() const;
 
   /// \return
   ///    The requested CPU id, or LLDB_INVALID_CPU_ID if this information is
   ///    not available for the current item.
   lldb::cpu_id_t GetCPU() const;
 
+  /// Get the approximate wall clock time in nanoseconds at which the current
+  /// trace item was executed. Each trace plug-in has a different definition for
+  /// what time 0 means.
+  ///
+  /// \param[out] estimated_time
+  ///     The trace item's estimtated timestamp, if available.
+  ///
+  /// \return
+  ///   true if the current trace item has an estimated timestamp associated
+  ///   with it, false otherwise.
+  bool GetWallClockTime(double &estimated_time) const;
+  /// \}
+
   bool IsValid() const;
 
   explicit operator bool() const;
 
 protected:
   lldb::TraceCursorSP m_opaque_sp;
 };
 } // namespace lldb
 
 #endif // LLDB_API_SBTRACECURSOR_H

lldb/source/API/SBTraceCursor.cpp

 }
 
 lldb::cpu_id_t SBTraceCursor::GetCPU() const {
   LLDB_INSTRUMENT_VA(this);
 
   return m_opaque_sp->GetCPU();
 }
 
+bool SBTraceCursor::GetWallClockTime(double &estimated_time) const {
+  LLDB_INSTRUMENT_VA(this);
+
+  if (const auto &maybe_wall_clock_time = m_opaque_sp->GetWallClockTime()) {
+    estimated_time = *maybe_wall_clock_time;
+    return true;
+  }
+  return false;
+}
+
 bool SBTraceCursor::IsValid() const {
   LLDB_INSTRUMENT_VA(this);
 
   return this->operator bool();
 }
 
 SBTraceCursor::operator bool() const {
   LLDB_INSTRUMENT_VA(this);
 
   return m_opaque_sp.get() != nullptr;
 }