llvm/Debuginfod/Debuginfod.h

0001 //===-- llvm/Debuginfod/Debuginfod.h - Debuginfod client --------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 ///
0009 /// \file
0010 /// This file contains several declarations for the debuginfod client and
0011 /// server. The client functions are getDefaultDebuginfodUrls,
0012 /// getCachedOrDownloadArtifact, and several convenience functions for specific
0013 /// artifact types: getCachedOrDownloadSource, getCachedOrDownloadExecutable,
0014 /// and getCachedOrDownloadDebuginfo. For the server, this file declares the
0015 /// DebuginfodLogEntry and DebuginfodServer structs, as well as the
0016 /// DebuginfodLog, DebuginfodCollection classes.
0017 ///
0018 //===----------------------------------------------------------------------===//
0019
0020 #ifndef LLVM_DEBUGINFOD_DEBUGINFOD_H
0021 #define LLVM_DEBUGINFOD_DEBUGINFOD_H
0022
0023 #include "HTTPServer.h"
0024
0025 #include "llvm/ADT/StringMap.h"
0026 #include "llvm/ADT/StringRef.h"
0027 #include "llvm/Object/BuildID.h"
0028 #include "llvm/Support/Error.h"
0029 #include "llvm/Support/MemoryBuffer.h"
0030 #include "llvm/Support/Mutex.h"
0031 #include "llvm/Support/RWMutex.h"
0032 #include "llvm/Support/Timer.h"
0033
0034 #include <chrono>
0035 #include <condition_variable>
0036 #include <optional>
0037 #include <queue>
0038
0039 namespace llvm {
0040
0041 /// Returns false if a debuginfod lookup can be determined to have no chance of
0042 /// succeeding.
0043 bool canUseDebuginfod();
0044
0045 /// Finds default array of Debuginfod server URLs by checking DEBUGINFOD_URLS
0046 /// environment variable.
0047 SmallVector<StringRef> getDefaultDebuginfodUrls();
0048
0049 /// Returns the cache key for a given debuginfod URL path.
0050 std::string getDebuginfodCacheKey(StringRef UrlPath);
0051
0052 /// Sets the list of debuginfod server URLs to query. This overrides the
0053 /// environment variable DEBUGINFOD_URLS.
0054 void setDefaultDebuginfodUrls(const SmallVector<StringRef> &URLs);
0055
0056 /// Finds a default local file caching directory for the debuginfod client,
0057 /// first checking DEBUGINFOD_CACHE_PATH.
0058 Expected<std::string> getDefaultDebuginfodCacheDirectory();
0059
0060 /// Finds a default timeout for debuginfod HTTP requests. Checks
0061 /// DEBUGINFOD_TIMEOUT environment variable, default is 90 seconds (90000 ms).
0062 std::chrono::milliseconds getDefaultDebuginfodTimeout();
0063
0064 /// Get the full URL path for a source request of a given BuildID and file
0065 /// path.
0066 std::string getDebuginfodSourceUrlPath(object::BuildIDRef ID,
0067                                        StringRef SourceFilePath);
0068
0069 /// Fetches a specified source file by searching the default local cache
0070 /// directory and server URLs.
0071 Expected<std::string> getCachedOrDownloadSource(object::BuildIDRef ID,
0072                                                 StringRef SourceFilePath);
0073
0074 /// Get the full URL path for an executable request of a given BuildID.
0075 std::string getDebuginfodExecutableUrlPath(object::BuildIDRef ID);
0076
0077 /// Fetches an executable by searching the default local cache directory and
0078 /// server URLs.
0079 Expected<std::string> getCachedOrDownloadExecutable(object::BuildIDRef ID);
0080
0081 /// Get the full URL path for a debug binary request of a given BuildID.
0082 std::string getDebuginfodDebuginfoUrlPath(object::BuildIDRef ID);
0083
0084 /// Fetches a debug binary by searching the default local cache directory and
0085 /// server URLs.
0086 Expected<std::string> getCachedOrDownloadDebuginfo(object::BuildIDRef ID);
0087
0088 /// Fetches any debuginfod artifact using the default local cache directory and
0089 /// server URLs.
0090 Expected<std::string> getCachedOrDownloadArtifact(StringRef UniqueKey,
0091                                                   StringRef UrlPath);
0092
0093 /// Fetches any debuginfod artifact using the specified local cache directory,
0094 /// server URLs, and request timeout (in milliseconds). If the artifact is
0095 /// found, uses the UniqueKey for the local cache file.
0096 Expected<std::string> getCachedOrDownloadArtifact(
0097     StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath,
0098     ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout);
0099
0100 class ThreadPoolInterface;
0101
0102 struct DebuginfodLogEntry {
0103   std::string Message;
0104   DebuginfodLogEntry() = default;
0105   DebuginfodLogEntry(const Twine &Message);
0106 };
0107
0108 class DebuginfodLog {
0109   std::mutex QueueMutex;
0110   std::condition_variable QueueCondition;
0111   std::queue<DebuginfodLogEntry> LogEntryQueue;
0112
0113 public:
0114   // Adds a log entry to end of the queue.
0115   void push(DebuginfodLogEntry Entry);
0116   // Adds a log entry to end of the queue.
0117   void push(const Twine &Message);
0118   // Blocks until there are log entries in the queue, then pops and returns the
0119   // first one.
0120   DebuginfodLogEntry pop();
0121 };
0122
0123 /// Tracks a collection of debuginfod artifacts on the local filesystem.
0124 class DebuginfodCollection {
0125   SmallVector<std::string, 1> Paths;
0126   sys::RWMutex BinariesMutex;
0127   StringMap<std::string> Binaries;
0128   sys::RWMutex DebugBinariesMutex;
0129   StringMap<std::string> DebugBinaries;
0130   Error findBinaries(StringRef Path);
0131   Expected<std::optional<std::string>> getDebugBinaryPath(object::BuildIDRef);
0132   Expected<std::optional<std::string>> getBinaryPath(object::BuildIDRef);
0133   // If the collection has not been updated since MinInterval, call update() and
0134   // return true. Otherwise return false. If update returns an error, return the
0135   // error.
0136   Expected<bool> updateIfStale();
0137   DebuginfodLog &Log;
0138   ThreadPoolInterface &Pool;
0139   Timer UpdateTimer;
0140   sys::Mutex UpdateMutex;
0141
0142   // Minimum update interval, in seconds, for on-demand updates triggered when a
0143   // build-id is not found.
0144   double MinInterval;
0145
0146 public:
0147   DebuginfodCollection(ArrayRef<StringRef> Paths, DebuginfodLog &Log,
0148                        ThreadPoolInterface &Pool, double MinInterval);
0149   Error update();
0150   Error updateForever(std::chrono::milliseconds Interval);
0151   Expected<std::string> findDebugBinaryPath(object::BuildIDRef);
0152   Expected<std::string> findBinaryPath(object::BuildIDRef);
0153 };
0154
0155 struct DebuginfodServer {
0156   HTTPServer Server;
0157   DebuginfodLog &Log;
0158   DebuginfodCollection &Collection;
0159   DebuginfodServer(DebuginfodLog &Log, DebuginfodCollection &Collection);
0160 };
0161
0162 } // end namespace llvm
0163
0164 #endif