forked from microsoft/vcpkg-tool
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
In several PRs, such as microsoft#908 and microsoft#1210 , it has bec…
…ome clear that we need a thread safe channel through which errors and warnings can both be reasonably reported. Now that microsoft#1279 is landed and functionally everything in the codebase uses ExpectedL, we can look at what the new thing that fixes issues is. Consider the following: ```c++ ExpectedL<T> example_api(int a); ExpectedL<std::unique_ptr<SourceControlFile>> try_load_port_manifest_text(StringView text, StringView control_path, MessageSink& warning_sink); ``` The reason this can't return the warnings through the ExpectedL channel is that we don't want the 'error' state to be engaged when there are merely warnings. Moreover, that these channels are different channels means that situations that might want to return errors and warnings together, as happens when parsing files, means that order relationships between errors and warnings is lost. It is probably a good idea in general to put warnings and errors about the same location next to each other in the output, but that's hard to do with this interface. Rather than multiplexing everything through the return value, this proposal is to multiplex only the success or failure through the return value, and report any specific error information through an out parameter. 1. Distinguish whether an overall operation succeeded or failed in the return value, but 2. record any errors or warnings via an out parameter. Applying this to the above gives: ```c++ Optional<T> example_api(MessageContext& context, int a); // unique_ptr is already 'optional' std::unique_ptr<SourceControlFile> try_load_port_manifest_text(MessageContext& context, StringView text, StringView control_path); ``` Issues this new mechanism fixes: * Errors and warnings can share the same channel and thus be printed together * The interface between code wanting to report events and the code wanting to consume them is a natural thread synchronization boundary. Other attempts to fix this have been incorrect by synchronizing individual print calls ( microsoft#1290 ) or complex enough that we are not sure they are correct by trying to recover boundaries by reparsing our own error output ( microsoft#908 ) * This shuts down the "error: error:" and similar bugs where it isn't clear who is formatting the overall error message vs. talking about individual components Known issues that are not fixed by this change: * This still doesn't make it easy for callers to programmatically handle specific types of errors. Currently, we have some APIs that still use explicit `std::error_code` because they want to do different things for 'file does not exist' vs. 'there was an I/O error'. Given that this condition isn't well served by the ExpectedL mechanism I don't want to wait until we have a better solution to it to proceed. * Because we aren't making the context parameter the 'success carrier' it's more complex to implement 'warnings as errors' or similar functionality where the caller decides how 'important' something is. I would be in favor of moving all success tests to the context parameter but I'm not proposing that because the other vcpkg maintainers do not like it. * Contextual information / stack problems aren't solved. However, the context parameter might be extended in the future to help with this.
- Loading branch information
1 parent
910db8b
commit 3138143
Showing
13 changed files
with
394 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,159 @@ | ||
#pragma once | ||
|
||
#include <vcpkg/base/expected.h> | ||
#include <vcpkg/base/messages.h> | ||
#include <vcpkg/base/optional.h> | ||
|
||
#include <mutex> | ||
#include <string> | ||
#include <type_traits> | ||
#include <vector> | ||
|
||
namespace vcpkg | ||
{ | ||
enum class DiagKind | ||
{ | ||
None, // foo.h: localized | ||
Message, // foo.h: message: localized | ||
Error, // foo.h: error: localized | ||
Warning, // foo.h: warning: localized | ||
Note, // foo.h: note: localized | ||
COUNT | ||
}; | ||
|
||
struct TextPosition | ||
{ | ||
// '0' indicates uninitialized; '1' is the first row/column | ||
int row = 0; | ||
int column = 0; | ||
}; | ||
|
||
struct DiagnosticLine | ||
{ | ||
DiagnosticLine(DiagKind kind, LocalizedString&& message) | ||
: m_kind(kind), m_origin(), m_position(), m_message(std::move(message)) | ||
{ | ||
} | ||
|
||
DiagnosticLine(DiagKind kind, StringView origin, LocalizedString&& message) | ||
: m_kind(kind), m_origin(origin.to_string()), m_position(), m_message(std::move(message)) | ||
{ | ||
} | ||
|
||
DiagnosticLine(DiagKind kind, StringView origin, TextPosition position, LocalizedString&& message) | ||
: m_kind(kind), m_origin(origin.to_string()), m_position(position), m_message(std::move(message)) | ||
{ | ||
} | ||
|
||
// Prints this diagnostic to the terminal. | ||
// Not thread safe: The console DiagnosticContext must apply its own synchronization. | ||
void print(MessageSink& sink) const; | ||
// Converts this message into a string | ||
// Prefer print() if possible because it applies color | ||
std::string to_string() const; | ||
void to_string(std::string& target) const; | ||
|
||
private: | ||
DiagKind m_kind; | ||
Optional<std::string> m_origin; | ||
TextPosition m_position; | ||
LocalizedString m_message; | ||
}; | ||
|
||
struct DiagnosticContext | ||
{ | ||
// Records a diagnostic. Implementations must make simultaneous calls of report() safe from multiple threads | ||
// and print entire DiagnosticLines as atomic units. Implementations are not required to synchronize with | ||
// other machinery like msg::print and friends. | ||
// | ||
// This serves to make multithreaded code that reports only via this mechanism safe. | ||
virtual void report(const DiagnosticLine& line) = 0; | ||
virtual void report(DiagnosticLine&& line) { report(line); } | ||
|
||
protected: | ||
~DiagnosticContext() = default; | ||
}; | ||
|
||
struct BufferedDiagnosticContext final : DiagnosticContext | ||
{ | ||
virtual void report(const DiagnosticLine& line) override; | ||
virtual void report(DiagnosticLine&& line) override; | ||
|
||
std::vector<DiagnosticLine> lines; | ||
|
||
// Prints all diagnostics to the terminal. | ||
// Not safe to use in the face of concurrent calls to report() | ||
void print(MessageSink& sink) const; | ||
// Converts this message into a string | ||
// Prefer print() if possible because it applies color | ||
// Not safe to use in the face of concurrent calls to report() | ||
std::string to_string() const; | ||
void to_string(std::string& target) const; | ||
|
||
private: | ||
std::mutex m_mtx; | ||
}; | ||
|
||
// If T Ty is an rvalue Optional<U>, typename UnwrapOptional<Ty>::type is the type necessary to forward U | ||
// Otherwise, there is no member UnwrapOptional<Ty>::type | ||
template<class Ty> | ||
struct UnwrapOptional | ||
{ | ||
// no member ::type, SFINAEs out when the input type is: | ||
// * not Optional | ||
// * not an rvalue | ||
// * volatile | ||
}; | ||
|
||
template<class Wrapped> | ||
struct UnwrapOptional<Optional<Wrapped>> | ||
{ | ||
// prvalue | ||
using type = Wrapped; | ||
using fwd = Wrapped&&; | ||
}; | ||
|
||
template<class Wrapped> | ||
struct UnwrapOptional<const Optional<Wrapped>> | ||
{ | ||
// const prvalue | ||
using type = Wrapped; | ||
using fwd = const Wrapped&&; | ||
}; | ||
|
||
template<class Wrapped> | ||
struct UnwrapOptional<Optional<Wrapped>&&> | ||
{ | ||
// xvalue | ||
using type = Wrapped&&; | ||
using fwd = Wrapped&&; | ||
}; | ||
|
||
template<class Wrapped> | ||
struct UnwrapOptional<const Optional<Wrapped>&&> | ||
{ | ||
// const xvalue | ||
using type = const Wrapped&&; | ||
using fwd = Wrapped&&; | ||
}; | ||
|
||
template<class Fn, class... Args> | ||
auto adapt_context_to_expected(Fn functor, Args&&... args) | ||
-> ExpectedL<typename UnwrapOptional<std::invoke_result_t<Fn, BufferedDiagnosticContext&, Args...>>::type> | ||
{ | ||
using Contained = typename UnwrapOptional<std::invoke_result_t<Fn, BufferedDiagnosticContext&, Args...>>::type; | ||
BufferedDiagnosticContext bdc; | ||
auto maybe_result = functor(bdc, std::forward<Args>(args)...); | ||
if (auto result = maybe_result.get()) | ||
{ | ||
// N.B.: This may be a move | ||
return ExpectedL<Contained>{ | ||
static_cast< | ||
typename UnwrapOptional<std::invoke_result_t<Fn, BufferedDiagnosticContext&, Args...>>::fwd>( | ||
*result), | ||
expected_left_tag}; | ||
} | ||
|
||
return ExpectedL<Contained>{LocalizedString::from_raw(bdc.to_string()), expected_right_tag}; | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.