blob: 053abaeada19e631f6badf2274e5add04d0b5160 [file] [log] [blame]
//===-- SBTrace.h -----------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
#ifndef LLDB_API_SBTRACE_H
#define LLDB_API_SBTRACE_H
#include "lldb/API/SBDefines.h"
#include "lldb/API/SBError.h"
class TraceImpl;
namespace lldb {
class LLDB_API SBTrace {
public:
SBTrace();
/// Obtain the trace data as raw bytes.
///
/// \param[out] error
/// An error explaining what went wrong.
///
/// \param[in] buf
/// Buffer to write the trace data to.
///
/// \param[in] size
/// The size of the buffer used to read the data. This is
/// also the size of the data intended to read. It is also
/// possible to partially read the trace data for some trace
/// technologies by specifying a smaller buffer.
///
/// \param[in] offset
/// The start offset to begin reading the trace data.
///
/// \param[in] thread_id
/// Tracing could be started for the complete process or a
/// single thread, in the first case the traceid obtained would
/// map to all the threads existing within the process and the
/// ones spawning later. The thread_id parameter can be used in
/// such a scenario to select the trace data for a specific
/// thread.
///
/// \return
/// The size of the trace data effectively read by the API call.
size_t GetTraceData(SBError &error, void *buf, size_t size, size_t offset = 0,
lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
/// Obtain any meta data as raw bytes for the tracing instance.
/// The input parameter definition is similar to the previous
/// function.
size_t GetMetaData(SBError &error, void *buf, size_t size, size_t offset = 0,
lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
/// Stop the tracing instance. Stopping the trace will also
/// lead to deletion of any gathered trace data.
///
/// \param[out] error
/// An error explaining what went wrong.
///
/// \param[in] thread_id
/// The trace id could map to a tracing instance for a thread
/// or could also map to a group of threads being traced with
/// the same trace options. A thread_id is normally optional
/// except in the case of tracing a complete process and tracing
/// needs to switched off on a particular thread.
/// A situation could occur where initially a thread (lets say
/// thread A) is being individually traced with a particular
/// trace id and then tracing is started on the complete
/// process, in this case thread A will continue without any
/// change. All newly spawned threads would be traced with the
/// trace id of the process.
/// Now if the StopTrace API is called for the whole process,
/// thread A will not be stopped and must be stopped separately.
void StopTrace(SBError &error,
lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
/// Get the trace configuration being used for the trace instance.
/// The threadid in the SBTraceOptions needs to be set when the
/// configuration used by a specific thread is being requested.
///
/// \param[out] options
/// The trace options actually used by the trace instance
/// would be filled by the API.
///
/// \param[out] error
/// An error explaining what went wrong.
void GetTraceConfig(SBTraceOptions &options, SBError &error);
lldb::user_id_t GetTraceUID();
explicit operator bool() const;
bool IsValid();
protected:
typedef std::shared_ptr<TraceImpl> TraceImplSP;
friend class SBProcess;
void SetTraceUID(lldb::user_id_t uid);
TraceImplSP m_trace_impl_sp;
lldb::ProcessSP GetSP() const;
void SetSP(const ProcessSP &process_sp);
lldb::ProcessWP m_opaque_wp;
};
} // namespace lldb
#endif // LLDB_API_SBTRACE_H