Line data    Source code

       1             : #pragma once
       2             : 
       3             : // This component provides an interface, `Logger`, that allows for the
       4             : // customization of how the library logs diagnostic and startup messages.
       5             : //
       6             : // Errors, when they occur, are typically returned as `Error` values (often as
       7             : // part of an `Expected` value). However, in "async" contexts where there is
       8             : // nowhere to return a value, the logger is used instead.
       9             : //
      10             : // `Logger`'s pure virtual member functions accept a callback function that is
      11             : // either invoked immediately or not invoked at all, depending on the
      12             : // implementation. Use of a callback is a compromise between always paying the
      13             : // overhead of forming log messages, and using the preprocessor to obscure a
      14             : // branch.
      15             : //
      16             : // The callback function accepts a single `std::ostream&` argument. Text
      17             : // inserted into the stream will appear in the resulting log message (assuming
      18             : // that an implementation invokes the callback). It is not necessary to append
      19             : // a newline character to the stream; an implementation will do that.
      20             : //
      21             : //     if (const int rcode = errno) {
      22             : //       logger.log_error([rcode](std::ostream& log) {
      23             : //         log << "Doodad frobnication failed: " << std::strerror(rcode);
      24             : //       });
      25             : //     }
      26             : //
      27             : // Non-pure virtual overloads of `log_error` are provided for convenience. One
      28             : // overload accepts an `Error`:
      29             : //
      30             : //     if (Error *error = expected_cake.if_error()) {
      31             : //       logger.log_error(*error);
      32             : //       return;
      33             : //     }
      34             : //
      35             : // The other overload accepts a `StringView`:
      36             : //
      37             : //     if (!success) {
      38             : //       logger.log_error("Something went wrong with the frobnication.");
      39             : //       return;
      40             : //     }
      41             : 
      42             : #include <functional>
      43             : #include <ostream>
      44             : 
      45             : #include "string_view.h"
      46             : 
      47             : namespace datadog {
      48             : namespace tracing {
      49             : 
      50             : struct Error;
      51             : 
      52             : class Logger {
      53             :  public:
      54             :   using LogFunc = std::function<void(std::ostream&)>;
      55             : 
      56         856 :   virtual ~Logger() {}
      57             : 
      58             :   virtual void log_error(const LogFunc&) = 0;
      59             :   virtual void log_startup(const LogFunc&) = 0;
      60             : 
      61             :   virtual void log_error(const Error&);
      62             :   virtual void log_error(StringView);
      63             : };
      64             : 
      65             : }  // namespace tracing
      66             : }  // namespace datadog