1//===----------------------------------------------------------------------===//
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 the declarations of the llvm::vfs::OutputFile class,
11/// which is a virtualized output file from output backend. \c OutputFile can be
12/// use a \c raw_pwrite_stream for writing, and are required to be `keep()` or
13/// `discard()` in the end.
14///
15//===----------------------------------------------------------------------===//
16
17#ifndef LLVM_SUPPORT_VIRTUALOUTPUTFILE_H
18#define LLVM_SUPPORT_VIRTUALOUTPUTFILE_H
19
20#include "llvm/ADT/FunctionExtras.h"
21#include "llvm/ADT/StringRef.h"
22#include "llvm/Support/Casting.h"
23#include "llvm/Support/Error.h"
24#include "llvm/Support/ExtensibleRTTI.h"
25#include "llvm/Support/raw_ostream.h"
26
27namespace llvm::vfs {
28
29class OutputFileImpl : public RTTIExtends<OutputFileImpl, RTTIRoot> {
30 LLVM_ABI void anchor() override;
31
32public:
33 LLVM_ABI static char ID;
34 ~OutputFileImpl() override = default;
35
36 virtual Error keep() = 0;
37 virtual Error discard() = 0;
38 virtual raw_pwrite_stream &getOS() = 0;
39};
40
41class NullOutputFileImpl final
42 : public RTTIExtends<NullOutputFileImpl, OutputFileImpl> {
43 LLVM_ABI void anchor() override;
44
45public:
46 LLVM_ABI static char ID;
47 Error keep() final { return Error::success(); }
48 Error discard() final { return Error::success(); }
49 raw_pwrite_stream &getOS() final { return OS; }
50
51private:
52 raw_null_ostream OS;
53};
54
55/// A virtualized output file that writes to a specific backend.
56///
57/// One of \a keep(), \a discard(), or \a discardOnDestroy() must be called
58/// before destruction.
59class OutputFile {
60public:
61 StringRef getPath() const { return Path; }
62
63 /// Check if \a keep() or \a discard() has already been called.
64 bool isOpen() const { return bool(Impl); }
65
66 explicit operator bool() const { return isOpen(); }
67
68 raw_pwrite_stream &getOS() {
69 assert(isOpen() && "Expected open output stream");
70 return Impl->getOS();
71 }
72 operator raw_pwrite_stream &() { return getOS(); }
73 template <class T> raw_ostream &operator<<(T &&V) {
74 return getOS() << std::forward<T>(V);
75 }
76
77 /// Keep an output. Errors if this fails.
78 ///
79 /// If it has already been closed, calls \a report_fatal_error().
80 ///
81 /// If there's an open proxy from \a createProxy(), calls \a discard() to
82 /// clean up temporaries followed by \a report_fatal_error().
83 LLVM_ABI Error keep();
84
85 /// Discard an output, cleaning up any temporary state. Errors if clean-up
86 /// fails.
87 ///
88 /// If it has already been closed, calls \a report_fatal_error().
89 LLVM_ABI Error discard();
90
91 /// Discard the output when destroying it if it's still open, sending the
92 /// result to \a Handler.
93 void discardOnDestroy(unique_function<void(Error E)> Handler) {
94 DiscardOnDestroyHandler = std::move(Handler);
95 }
96
97 /// Create a proxy stream for clients that need to pass an owned stream to a
98 /// producer. Errors if there's already a proxy. The proxy must be deleted
99 /// before calling \a keep(). The proxy will crash if it's written to after
100 /// calling \a discard().
101 LLVM_ABI Expected<std::unique_ptr<raw_pwrite_stream>> createProxy();
102
103 bool hasOpenProxy() const { return OpenProxy; }
104
105 /// Take the implementation.
106 ///
107 /// \pre \a hasOpenProxy() is false.
108 /// \pre \a discardOnDestroy() has not been called.
109 std::unique_ptr<OutputFileImpl> takeImpl() {
110 assert(!hasOpenProxy() && "Unexpected open proxy");
111 assert(!DiscardOnDestroyHandler && "Unexpected discard handler");
112 return std::move(Impl);
113 }
114
115 /// Check whether this is a null output file.
116 bool isNull() const { return Impl && isa<NullOutputFileImpl>(Val: *Impl); }
117
118 OutputFile() = default;
119
120 explicit OutputFile(const Twine &Path, std::unique_ptr<OutputFileImpl> Impl)
121 : Path(Path.str()), Impl(std::move(Impl)) {
122 assert(this->Impl && "Expected open output file");
123 }
124
125 ~OutputFile() { destroy(); }
126 OutputFile(OutputFile &&O) { moveFrom(O); }
127 OutputFile &operator=(OutputFile &&O) {
128 destroy();
129 return moveFrom(O);
130 }
131
132private:
133 /// Destroy \a Impl. Reports fatal error if the file is open and there's no
134 /// handler from \a discardOnDestroy().
135 LLVM_ABI void destroy();
136 OutputFile &moveFrom(OutputFile &O) {
137 Path = std::move(O.Path);
138 Impl = std::move(O.Impl);
139 DiscardOnDestroyHandler = std::move(O.DiscardOnDestroyHandler);
140 OpenProxy = O.OpenProxy;
141 O.OpenProxy = nullptr;
142 return *this;
143 }
144
145 std::string Path;
146 std::unique_ptr<OutputFileImpl> Impl;
147 unique_function<void(Error E)> DiscardOnDestroyHandler;
148
149 class TrackedProxy;
150 TrackedProxy *OpenProxy = nullptr;
151};
152
153/// Update \p File to silently discard itself if it's still open when it's
154/// destroyed.
155inline void consumeDiscardOnDestroy(OutputFile &File) {
156 File.discardOnDestroy(Handler: consumeError);
157}
158
159/// Update \p File to silently discard itself if it's still open when it's
160/// destroyed.
161inline Expected<OutputFile> consumeDiscardOnDestroy(Expected<OutputFile> File) {
162 if (File)
163 consumeDiscardOnDestroy(File&: *File);
164 return File;
165}
166
167} // namespace llvm::vfs
168
169#endif // LLVM_SUPPORT_VIRTUALOUTPUTFILE_H
170