clang-tools
7.0.0
llvm.src
tools
clang
tools
extra
clangd
Trace.h
Go to the documentation of this file.
1
//===--- Trace.h - Performance tracing facilities ---------------*- C++ -*-===//
2
//
3
// The LLVM Compiler Infrastructure
4
//
5
// This file is distributed under the University of Illinois Open Source
6
// License. See LICENSE.TXT for details.
7
//
8
//===----------------------------------------------------------------------===//
9
//
10
// Supports writing performance traces describing clangd's behavior.
11
// Traces are consumed by implementations of the EventTracer interface.
12
//
13
//
14
// All APIs are no-ops unless a Session is active (created by ClangdMain).
15
//
16
//===----------------------------------------------------------------------===//
17
18
#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
19
#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
20
21
#include "
Context.h
"
22
#include "
Function.h
"
23
#include "llvm/ADT/Twine.h"
24
#include "llvm/Support/JSON.h"
25
#include "llvm/Support/raw_ostream.h"
26
27
namespace
clang
{
28
namespace
clangd {
29
namespace
trace {
30
31
/// A consumer of trace events. The events are produced by Spans and trace::log.
32
/// Implmentations of this interface must be thread-safe.
33
class
EventTracer
{
34
public
:
35
virtual
~EventTracer
() =
default
;
36
37
/// Called when event that has a duration starts. \p Name describes the event.
38
/// Returns a derived context that will be destroyed when the event ends.
39
/// Usually implementations will store an object in the returned context
40
/// whose destructor records the end of the event.
41
/// The args are *Args, only complete when the event ends.
42
virtual
Context
beginSpan
(llvm::StringRef
Name
, llvm::json::Object *Args) = 0;
43
// Called when a Span is destroyed (it may still be active on other threads).
44
// beginSpan() and endSpan() will always form a proper stack on each thread.
45
// The Context returned by beginSpan is active, but Args is not ready.
46
// Tracers should not override this unless they need to observe strict
47
// per-thread nesting. Instead they should observe context destruction.
48
virtual
void
endSpan
(){};
49
50
/// Called for instant events.
51
virtual
void
instant
(llvm::StringRef Name, llvm::json::Object &&Args) = 0;
52
};
53
54
/// Sets up a global EventTracer that consumes events produced by Span and
55
/// trace::log. Only one TracingSession can be active at a time and it should be
56
/// set up before calling any clangd-specific functions.
57
class
Session
{
58
public
:
59
Session
(
EventTracer
&Tracer);
60
~
Session
();
61
};
62
63
/// Create an instance of EventTracer that produces an output in the Trace Event
64
/// format supported by Chrome's trace viewer (chrome://tracing).
65
///
66
/// The format is documented here:
67
/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
68
std::unique_ptr<EventTracer>
createJSONTracer
(llvm::raw_ostream &OS,
69
bool
Pretty =
false
);
70
71
/// Records a single instant event, associated with the current thread.
72
void
log
(
const
llvm::Twine &
Name
);
73
74
/// Records an event whose duration is the lifetime of the Span object.
75
/// This lifetime is extended when the span's context is reused.
76
///
77
/// This is the main public interface for producing tracing events.
78
///
79
/// Arbitrary JSON metadata can be attached while this span is active:
80
/// SPAN_ATTACH(MySpan, "Payload", SomeJSONExpr);
81
///
82
/// SomeJSONExpr is evaluated and copied only if actually needed.
83
class
Span
{
84
public
:
85
Span
(llvm::Twine Name);
86
~
Span
();
87
88
/// Mutable metadata, if this span is interested.
89
/// Prefer to use SPAN_ATTACH rather than accessing this directly.
90
llvm::json::Object *
const
Args
;
91
92
private
:
93
WithContext
RestoreCtx;
94
};
95
96
/// Attach a key-value pair to a Span event.
97
/// This is not threadsafe when used with the same Span.
98
#define SPAN_ATTACH(S, Name, Expr) \
99
do { \
100
if (auto *Args = (S).Args) \
101
(*Args)[Name] = Expr; \
102
} while (0)
103
104
}
// namespace trace
105
}
// namespace clangd
106
}
// namespace clang
107
108
#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
Name
llvm::StringRef Name
Definition:
CodeComplete.cpp:190
clang::clangd::trace::Session
Sets up a global EventTracer that consumes events produced by Span and trace::log.
Definition:
Trace.h:57
Context.h
clang::clangd::trace::EventTracer::~EventTracer
virtual ~EventTracer()=default
clang::clangd::trace::EventTracer::instant
virtual void instant(llvm::StringRef Name, llvm::json::Object &&Args)=0
Called for instant events.
clang::clangd::trace::log
void log(const Twine &Message)
Definition:
Trace.cpp:203
clang::clangd::Context
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition:
Context.h:70
clang::clangd::WithContext
WithContext replaces Context::current() with a provided scope.
Definition:
Context.h:190
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition:
ChangeNamespace.cpp:16
Function.h
clang::clangd::trace::createJSONTracer
std::unique_ptr< EventTracer > createJSONTracer(llvm::raw_ostream &OS, bool Pretty)
Create an instance of EventTracer that produces an output in the Trace Event format supported by Chro...
Definition:
Trace.cpp:198
clang::clangd::trace::Span::Args
llvm::json::Object *const Args
Mutable metadata, if this span is interested.
Definition:
Trace.h:90
clang::clangd::trace::Span
Records an event whose duration is the lifetime of the Span object.
Definition:
Trace.h:83
clang::clangd::trace::EventTracer::beginSpan
virtual Context beginSpan(llvm::StringRef Name, llvm::json::Object *Args)=0
Called when event that has a duration starts.
clang::clangd::trace::EventTracer
A consumer of trace events.
Definition:
Trace.h:33
clang::clangd::trace::EventTracer::endSpan
virtual void endSpan()
Definition:
Trace.h:48
Generated on Thu Aug 23 2018 18:51:33 for clang-tools by
1.8.13