LLVM 20.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"
32#include "llvm/Support/Timer.h"
33
34#include <chrono>
35#include <condition_variable>
36#include <optional>
37#include <queue>
38
39namespace llvm {
40
41/// Returns false if a debuginfod lookup can be determined to have no chance of
42/// succeeding.
43bool canUseDebuginfod();
44
45/// Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS
46/// environment variable.
47SmallVector<StringRef> getDefaultDebuginfodUrls();
48
49/// Returns the cache key for a given debuginfod URL path.
50std::string getDebuginfodCacheKey(StringRef UrlPath);
51
52/// Sets the list of debuginfod server URLs to query. This overrides the
53/// environment variable DEBUGINFOD_URLS.
54void setDefaultDebuginfodUrls(const SmallVector<StringRef> &URLs);
55
56/// Finds a default local file caching directory for the debuginfod client,
57/// first checking DEBUGINFOD_CACHE_PATH.
58Expected<std::string> getDefaultDebuginfodCacheDirectory();
59
60/// Finds a default timeout for debuginfod HTTP requests. Checks
61/// DEBUGINFOD_TIMEOUT environment variable, default is 90 seconds (90000 ms).
62std::chrono::milliseconds getDefaultDebuginfodTimeout();
63
64/// Get the full URL path for a source request of a given BuildID and file
65/// path.
67 StringRef SourceFilePath);
68
69/// Fetches a specified source file by searching the default local cache
70/// directory and server URLs.
72 StringRef SourceFilePath);
73
74/// Get the full URL path for an executable request of a given BuildID.
76
77/// Fetches an executable by searching the default local cache directory and
78/// server URLs.
80
81/// Get the full URL path for a debug binary request of a given BuildID.
83
84/// Fetches a debug binary by searching the default local cache directory and
85/// server URLs.
87
88/// Fetches any debuginfod artifact using the default local cache directory and
89/// server URLs.
91 StringRef UrlPath);
92
93/// Fetches any debuginfod artifact using the specified local cache directory,
94/// server URLs, and request timeout (in milliseconds). If the artifact is
95/// found, uses the UniqueKey for the local cache file.
97 StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath,
98 ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout);
99
101
103 std::string Message;
106};
107
109 std::mutex QueueMutex;
110 std::condition_variable QueueCondition;
111 std::queue<DebuginfodLogEntry> LogEntryQueue;
112
113public:
114 // Adds a log entry to end of the queue.
115 void push(DebuginfodLogEntry Entry);
116 // Adds a log entry to end of the queue.
117 void push(const Twine &Message);
118 // Blocks until there are log entries in the queue, then pops and returns the
119 // first one.
121};
122
123/// Tracks a collection of debuginfod artifacts on the local filesystem.
126 sys::RWMutex BinariesMutex;
127 StringMap<std::string> Binaries;
128 sys::RWMutex DebugBinariesMutex;
129 StringMap<std::string> DebugBinaries;
130 Error findBinaries(StringRef Path);
133 // If the collection has not been updated since MinInterval, call update() and
134 // return true. Otherwise return false. If update returns an error, return the
135 // error.
136 Expected<bool> updateIfStale();
137 DebuginfodLog &Log;
139 Timer UpdateTimer;
140 sys::Mutex UpdateMutex;
141
142 // Minimum update interval, in seconds, for on-demand updates triggered when a
143 // build-id is not found.
144 double MinInterval;
145
146public:
148 ThreadPoolInterface &Pool, double MinInterval);
149 Error update();
150 Error updateForever(std::chrono::milliseconds Interval);
153};
154
160};
161
162} // end namespace llvm
163
164#endif
This file defines the StringMap class.
This file declares a library for handling Build IDs and using them to find debug info.
This file contains the declarations of the HTTPServer and HTTPServerRequest classes,...
std::pair< uint64_t, uint64_t > Interval
Tracks a collection of debuginfod artifacts on the local filesystem.
Definition: Debuginfod.h:124
Expected< std::string > findBinaryPath(object::BuildIDRef)
Definition: Debuginfod.cpp:501
Error updateForever(std::chrono::milliseconds Interval)
Definition: Debuginfod.cpp:387
Expected< std::string > findDebugBinaryPath(object::BuildIDRef)
Definition: Debuginfod.cpp:533
DebuginfodLogEntry pop()
Definition: Debuginfod.cpp:335
void push(DebuginfodLogEntry Entry)
Definition: Debuginfod.cpp:327
Lightweight error class with error context and mandatory checking.
Definition: Error.h:160
Tagged union holding either a T or a Error.
Definition: Error.h:481
An HTTP server which can listen on a single TCP/IP port for HTTP requests and delgate them to the app...
Definition: HTTPServer.h:99
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1209
StringMap - This is an unconventional map that is specialized for handling keys that are "strings",...
Definition: StringMap.h:128
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
This defines the abstract base interface for a ThreadPool allowing asynchronous parallel execution on...
Definition: ThreadPool.h:49
This class is used to track the amount of time spent between invocations of its startTimer()/stopTime...
Definition: Timer.h:79
Twine - A lightweight data structure for efficiently representing the concatenation of temporary valu...
Definition: Twine.h:81
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
Expected< std::string > getCachedOrDownloadExecutable(object::BuildIDRef ID)
Fetches an executable by searching the default local cache directory and server URLs.
std::string getDebuginfodCacheKey(StringRef UrlPath)
Returns the cache key for a given debuginfod URL path.
Definition: Debuginfod.cpp:57
SmallVector< StringRef > getDefaultDebuginfodUrls()
Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS environment variable.
Definition: Debuginfod.cpp:71
std::string getDebuginfodSourceUrlPath(object::BuildIDRef ID, StringRef SourceFilePath)
Get the full URL path for a source request of a given BuildID and file path.
Expected< std::string > getCachedOrDownloadDebuginfo(object::BuildIDRef ID)
Fetches a debug binary by searching the default local cache directory and server URLs.
std::string getDebuginfodExecutableUrlPath(object::BuildIDRef ID)
Get the full URL path for an executable request of a given BuildID.
Expected< std::string > getCachedOrDownloadArtifact(StringRef UniqueKey, StringRef UrlPath)
Fetches any debuginfod artifact using the default local cache directory and server URLs.
Definition: Debuginfod.cpp:163
std::string getDebuginfodDebuginfoUrlPath(object::BuildIDRef ID)
Get the full URL path for a debug binary request of a given BuildID.
Expected< std::string > getCachedOrDownloadSource(object::BuildIDRef ID, StringRef SourceFilePath)
Fetches a specified source file by searching the default local cache directory and server URLs.
std::chrono::milliseconds getDefaultDebuginfodTimeout()
Finds a default timeout for debuginfod HTTP requests.
Definition: Debuginfod.cpp:109
void setDefaultDebuginfodUrls(const SmallVector< StringRef > &URLs)
Sets the list of debuginfod server URLs to query.
Definition: Debuginfod.cpp:90
bool canUseDebuginfod()
Returns false if a debuginfod lookup can be determined to have no chance of succeeding.
Definition: Debuginfod.cpp:67
Expected< std::string > getDefaultDebuginfodCacheDirectory()
Finds a default local file caching directory for the debuginfod client, first checking DEBUGINFOD_CAC...
Definition: Debuginfod.cpp:97
DebuginfodLog & Log
Definition: Debuginfod.h:157
DebuginfodCollection & Collection
Definition: Debuginfod.h:158