1 //===-- llvm/Support/Signposts.h - Interval debug annotations ---*- 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 /// \file Some OS's provide profilers that allow applications to provide custom
11 /// annotations to the profiler. For example, on Xcode 10 and later 'signposts'
12 /// can be emitted by the application and these will be rendered to the Points
13 /// of Interest track on the instruments timeline.
14 //
15 //===----------------------------------------------------------------------===//
16 
17 #ifndef LLVM_SUPPORT_SIGNPOSTS_H
18 #define LLVM_SUPPORT_SIGNPOSTS_H
19 
20 #include "llvm/ADT/StringRef.h"
21 #include "llvm/Config/llvm-config.h"
22 #include <memory>
23 
24 #if LLVM_SUPPORT_XCODE_SIGNPOSTS
25 #include <Availability.h>
26 #include <os/signpost.h>
27 #endif
28 
29 #define SIGNPOSTS_AVAILABLE()                                                  \
30   __builtin_available(macos 10.14, iOS 12, tvOS 12, watchOS 5, *)
31 
32 namespace llvm {
33 class SignpostEmitterImpl;
34 
35 /// Manages the emission of signposts into the recording method supported by
36 /// the OS.
37 class SignpostEmitter {
38   std::unique_ptr<SignpostEmitterImpl> Impl;
39 
40 public:
41   SignpostEmitter();
42   ~SignpostEmitter();
43 
44   bool isEnabled() const;
45 
46   /// Begin a signposted interval for a given object.
47   void startInterval(const void *O, StringRef Name);
48 
49 #if LLVM_SUPPORT_XCODE_SIGNPOSTS
50   os_log_t &getLogger() const;
51   os_signpost_id_t getSignpostForObject(const void *O);
52 #endif
53 
54   /// A macro to take advantage of the special format string handling
55   /// in the os_signpost API. The format string substitution is
56   /// deferred to the log consumer and done outside of the
57   /// application.
58 #if LLVM_SUPPORT_XCODE_SIGNPOSTS
59 #define SIGNPOST_EMITTER_START_INTERVAL(SIGNPOST_EMITTER, O, ...)              \
60   do {                                                                         \
61     if ((SIGNPOST_EMITTER).isEnabled())                                        \
62       if (SIGNPOSTS_AVAILABLE())                                               \
63         os_signpost_interval_begin((SIGNPOST_EMITTER).getLogger(),             \
64                                    (SIGNPOST_EMITTER).getSignpostForObject(O), \
65                                    "LLVM Timers", __VA_ARGS__);                \
66   } while (0)
67 #else
68 #define SIGNPOST_EMITTER_START_INTERVAL(SIGNPOST_EMITTER, O, ...)              \
69   do {                                                                         \
70   } while (0)
71 #endif
72 
73   /// End a signposted interval for a given object.
74   void endInterval(const void *O);
75 };
76 
77 } // end namespace llvm
78 
79 #endif // LLVM_SUPPORT_SIGNPOSTS_H
80