LLVM  17.0.0git
Debuginfod.h
Go to the documentation of this file.
1 //===-- llvm/Debuginfod/Debuginfod.h - Debuginfod client --------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// This file contains several declarations for the debuginfod client and
11 /// server. The client functions are getDefaultDebuginfodUrls,
12 /// getCachedOrDownloadArtifact, and several convenience functions for specific
13 /// artifact types: getCachedOrDownloadSource, getCachedOrDownloadExecutable,
14 /// and getCachedOrDownloadDebuginfo. For the server, this file declares the
15 /// DebuginfodLogEntry and DebuginfodServer structs, as well as the
16 /// DebuginfodLog, DebuginfodCollection classes.
17 ///
18 //===----------------------------------------------------------------------===//
19 
20 #ifndef LLVM_DEBUGINFOD_DEBUGINFOD_H
21 #define LLVM_DEBUGINFOD_DEBUGINFOD_H
22 
23 #include "HTTPServer.h"
24 
25 #include "llvm/ADT/StringMap.h"
26 #include "llvm/ADT/StringRef.h"
27 #include "llvm/Object/BuildID.h"
28 #include "llvm/Support/Error.h"
30 #include "llvm/Support/Mutex.h"
31 #include "llvm/Support/RWMutex.h"
32 #include "llvm/Support/Timer.h"
33 
34 #include <chrono>
35 #include <condition_variable>
36 #include <optional>
37 #include <queue>
38 
39 namespace llvm {
40 
41 /// Returns false if a debuginfod lookup can be determined to have no chance of
42 /// succeeding.
43 bool canUseDebuginfod();
44 
45 /// Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS
46 /// environment variable.
47 SmallVector<StringRef> getDefaultDebuginfodUrls();
48 
49 /// Finds a default local file caching directory for the debuginfod client,
50 /// first checking DEBUGINFOD_CACHE_PATH.
51 Expected<std::string> getDefaultDebuginfodCacheDirectory();
52 
53 /// Finds a default timeout for debuginfod HTTP requests. Checks
54 /// DEBUGINFOD_TIMEOUT environment variable, default is 90 seconds (90000 ms).
55 std::chrono::milliseconds getDefaultDebuginfodTimeout();
56 
57 /// Fetches a specified source file by searching the default local cache
58 /// directory and server URLs.
59 Expected<std::string> getCachedOrDownloadSource(object::BuildIDRef ID,
60  StringRef SourceFilePath);
61 
62 /// Fetches an executable by searching the default local cache directory and
63 /// server URLs.
64 Expected<std::string> getCachedOrDownloadExecutable(object::BuildIDRef ID);
65 
66 /// Fetches a debug binary by searching the default local cache directory and
67 /// server URLs.
68 Expected<std::string> getCachedOrDownloadDebuginfo(object::BuildIDRef ID);
69 
70 /// Fetches any debuginfod artifact using the default local cache directory and
71 /// server URLs.
72 Expected<std::string> getCachedOrDownloadArtifact(StringRef UniqueKey,
73  StringRef UrlPath);
74 
75 /// Fetches any debuginfod artifact using the specified local cache directory,
76 /// server URLs, and request timeout (in milliseconds). If the artifact is
77 /// found, uses the UniqueKey for the local cache file.
78 Expected<std::string> getCachedOrDownloadArtifact(
79  StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath,
80  ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout);
81 
82 class ThreadPool;
83 
85  std::string Message;
86  DebuginfodLogEntry() = default;
88 };
89 
91  std::mutex QueueMutex;
92  std::condition_variable QueueCondition;
93  std::queue<DebuginfodLogEntry> LogEntryQueue;
94 
95 public:
96  // Adds a log entry to end of the queue.
97  void push(DebuginfodLogEntry Entry);
98  // Adds a log entry to end of the queue.
99  void push(const Twine &Message);
100  // Blocks until there are log entries in the queue, then pops and returns the
101  // first one.
103 };
104 
105 /// Tracks a collection of debuginfod artifacts on the local filesystem.
108  sys::RWMutex BinariesMutex;
109  StringMap<std::string> Binaries;
110  sys::RWMutex DebugBinariesMutex;
111  StringMap<std::string> DebugBinaries;
112  Error findBinaries(StringRef Path);
115  // If the collection has not been updated since MinInterval, call update() and
116  // return true. Otherwise return false. If update returns an error, return the
117  // error.
118  Expected<bool> updateIfStale();
119  DebuginfodLog &Log;
120  ThreadPool &Pool;
121  Timer UpdateTimer;
122  sys::Mutex UpdateMutex;
123 
124  // Minimum update interval, in seconds, for on-demand updates triggered when a
125  // build-id is not found.
126  double MinInterval;
127 
128 public:
130  ThreadPool &Pool, double MinInterval);
131  Error update();
132  Error updateForever(std::chrono::milliseconds Interval);
135 };
136 
142 };
143 
144 } // end namespace llvm
145 
146 #endif
llvm::DebuginfodLog::pop
DebuginfodLogEntry pop()
Definition: Debuginfod.cpp:288
MemoryBuffer.h
llvm
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
llvm::DebuginfodLogEntry::DebuginfodLogEntry
DebuginfodLogEntry()=default
llvm::DebuginfodCollection::DebuginfodCollection
DebuginfodCollection(ArrayRef< StringRef > Paths, DebuginfodLog &Log, ThreadPool &Pool, double MinInterval)
Definition: Debuginfod.cpp:303
HTTPServer.h
llvm::object::BuildIDRef
ArrayRef< uint8_t > BuildIDRef
A reference to a BuildID in binary form.
Definition: BuildID.h:28
llvm::ThreadPool
A ThreadPool for asynchronous parallel execution on a defined number of threads.
Definition: ThreadPool.h:52
StringRef.h
RWMutex.h
llvm::SmallVector< std::string, 1 >
llvm::getCachedOrDownloadExecutable
Expected< std::string > getCachedOrDownloadExecutable(object::BuildIDRef ID)
Fetches an executable by searching the default local cache directory and server URLs.
Error.h
llvm::canUseDebuginfod
bool canUseDebuginfod()
Returns false if a debuginfod lookup can be determined to have no chance of succeeding.
Definition: Debuginfod.cpp:58
llvm::Timer
This class is used to track the amount of time spent between invocations of its startTimer()/stopTime...
Definition: Timer.h:81
llvm::DebuginfodLogEntry::Message
std::string Message
Definition: Debuginfod.h:85
llvm::Expected
Tagged union holding either a T or a Error.
Definition: APFloat.h:41
llvm::getDefaultDebuginfodTimeout
std::chrono::milliseconds getDefaultDebuginfodTimeout()
Finds a default timeout for debuginfod HTTP requests.
Definition: Debuginfod.cpp:86
llvm::DebuginfodCollection::findBinaryPath
Expected< std::string > findBinaryPath(object::BuildIDRef)
Definition: Debuginfod.cpp:453
llvm::DebuginfodCollection::update
Error update()
Definition: Debuginfod.cpp:311
llvm::getCachedOrDownloadArtifact
Expected< std::string > getCachedOrDownloadArtifact(StringRef UniqueKey, StringRef UrlPath)
Fetches any debuginfod artifact using the default local cache directory and server URLs.
Definition: Debuginfod.cpp:124
llvm::getDefaultDebuginfodUrls
SmallVector< StringRef > getDefaultDebuginfodUrls()
Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS environment variable.
Definition: Debuginfod.cpp:62
llvm::sys::SmartMutex< false >
llvm::DebuginfodServer::Server
HTTPServer Server
Definition: Debuginfod.h:138
llvm::DebuginfodLog
Definition: Debuginfod.h:90
llvm::StringMap< std::string >
BuildID.h
Timer.h
llvm::Interval
Interval Class - An Interval is a set of nodes defined such that every node in the interval has all o...
Definition: Interval.h:36
llvm::getDefaultDebuginfodCacheDirectory
Expected< std::string > getDefaultDebuginfodCacheDirectory()
Finds a default local file caching directory for the debuginfod client, first checking DEBUGINFOD_CAC...
Definition: Debuginfod.cpp:74
llvm::DebuginfodServer::DebuginfodServer
DebuginfodServer(DebuginfodLog &Log, DebuginfodCollection &Collection)
Definition: Debuginfod.cpp:510
llvm::DebuginfodServer
Definition: Debuginfod.h:137
llvm::getCachedOrDownloadDebuginfo
Expected< std::string > getCachedOrDownloadDebuginfo(object::BuildIDRef ID)
Fetches a debug binary by searching the default local cache directory and server URLs.
llvm::ArrayRef< uint8_t >
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
Mutex.h
llvm::DebuginfodCollection::updateForever
Error updateForever(std::chrono::milliseconds Interval)
Definition: Debuginfod.cpp:339
llvm::DebuginfodLog::push
void push(DebuginfodLogEntry Entry)
Definition: Debuginfod.cpp:280
llvm::Twine
Twine - A lightweight data structure for efficiently representing the concatenation of temporary valu...
Definition: Twine.h:81
llvm::Error
Lightweight error class with error context and mandatory checking.
Definition: Error.h:156
llvm::DebuginfodCollection
Tracks a collection of debuginfod artifacts on the local filesystem.
Definition: Debuginfod.h:106
llvm::DebuginfodServer::Log
DebuginfodLog & Log
Definition: Debuginfod.h:139
llvm::DebuginfodCollection::findDebugBinaryPath
Expected< std::string > findDebugBinaryPath(object::BuildIDRef)
Definition: Debuginfod.cpp:485
llvm::HTTPServer
An HTTP server which can listen on a single TCP/IP port for HTTP requests and delgate them to the app...
Definition: HTTPServer.h:89
llvm::sys::SmartRWMutex< false >
llvm::getCachedOrDownloadSource
Expected< std::string > getCachedOrDownloadSource(object::BuildIDRef ID, StringRef SourceFilePath)
Fetches a specified source file by searching the default local cache directory and server URLs.
StringMap.h
llvm::DebuginfodServer::Collection
DebuginfodCollection & Collection
Definition: Debuginfod.h:140
llvm::DebuginfodLogEntry
Definition: Debuginfod.h:84