gcc/opt-problem.h

   1 /* Rich information on why an optimization wasn't possible.
   2    Copyright (C) 2018-2023 Free Software Foundation, Inc.
   3    Contributed by David Malcolm <dmalcolm@redhat.com>.
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 3, or (at your option) any later
  10 version.
  11
  12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GCC; see the file COPYING3.  If not see
  19 <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef GCC_OPT_PROBLEM_H
  22 #define GCC_OPT_PROBLEM_H
  23
  24 #include "diagnostic-core.h" /* for ATTRIBUTE_GCC_DIAG.  */
  25 #include "optinfo.h" /* for optinfo.  */
  26
  27 /* This header declares a family of wrapper classes for tracking a
  28    success/failure value, while optionally supporting propagating an
  29    opt_problem * describing any failure back up the call stack.
  30
  31    For instance, at the deepest point of the callstack where the failure
  32    happens, rather than:
  33
  34      if (!check_something ())
  35        {
  36          if (dump_enabled_p ())
  37            dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
  38                             "foo is unsupported.\n");
  39          return false;
  40        }
  41      // [...more checks...]
  42
  43      // All checks passed:
  44      return true;
  45
  46    we can capture the cause of the failure via:
  47
  48      if (!check_something ())
  49        return opt_result::failure_at (stmt, "foo is unsupported");
  50      // [...more checks...]
  51
  52      // All checks passed:
  53      return opt_result::success ();
  54
  55    which effectively returns true or false, whilst recording any problem.
  56
  57    opt_result::success and opt_result::failure return opt_result values
  58    which "looks like" true/false respectively, via operator bool().
  59    If dump_enabled_p, then opt_result::failure also creates an opt_problem *,
  60    capturing the pertinent data (here, "foo is unsupported " and "stmt").
  61    If dumps are disabled, then opt_problem instances aren't
  62    created, and it's equivalent to just returning a bool.
  63
  64    The opt_problem can be propagated via opt_result values back up
  65    the call stack to where it makes most sense to the user.
  66    For instance, rather than:
  67
  68      bool ok = try_something_that_might_fail ();
  69      if (!ok)
  70        {
  71          if (dump_enabled_p ())
  72            dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
  73                             "some message.\n");
  74          return false;
  75        }
  76
  77    we can replace the bool with an opt_result, so if dump_enabled_p, we
  78    assume that if try_something_that_might_fail, an opt_problem * will be
  79    created, and we can propagate it up the call chain:
  80
  81      opt_result ok = try_something_that_might_fail ();
  82      if (!ok)
  83        {
  84          if (dump_enabled_p ())
  85            dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
  86                             "some message.\n");
  87          return ok; // propagating the opt_result
  88        }
  89
  90    opt_result is an opt_wrapper<bool>, where opt_wrapper<T> is a base
  91    class for wrapping a T, optionally propagating an opt_problem in
  92    case of failure_at (when dumps are enabled).  Similarly,
  93    opt_pointer_wrapper<T> can be used to wrap pointer types (where non-NULL
  94    signifies success, NULL signifies failure).
  95
  96    In all cases, opt_wrapper<T> acts as if the opt_problem were one of its
  97    fields, but the opt_problem is actually stored in a global, so that when
  98    compiled, an opt_wrapper<T> is effectively just a T, so that we're
  99    still just passing e.g. a bool around; the opt_wrapper<T> classes
 100    simply provide type-checking and an API to ensure that we provide
 101    error-messages deep in the callstack at the places where problems
 102    occur, and that we propagate them.  This also avoids having
 103    to manage the ownership of the opt_problem instances.
 104
 105    Using opt_result and opt_wrapper<T> documents the intent of the code
 106    for the places where we represent success values, and allows the C++ type
 107    system to track where the deepest points in the callstack are where we
 108    need to emit the failure messages from.  */
 109
 110 /* A bundle of information about why an optimization failed (e.g.
 111    vectorization), and the location in both the user's code and
 112    in GCC itself where the problem occurred.
 113
 114    Instances are created by static member functions in opt_wrapper
 115    subclasses, such as opt_result::failure.
 116
 117    Instances are only created when dump_enabled_p ().  */
 118
 119 class opt_problem
 120 {
 121  public:
 122   static opt_problem *get_singleton () { return s_the_problem; }
 123
 124   opt_problem (const dump_location_t &loc,
 125                const char *fmt, va_list *ap)
 126     ATTRIBUTE_GCC_DUMP_PRINTF (3, 0);
 127
 128   const dump_location_t &
 129   get_dump_location () const { return m_optinfo.get_dump_location (); }
 130
 131   const optinfo & get_optinfo () const { return m_optinfo; }
 132
 133   void emit_and_clear ();
 134
 135  private:
 136   optinfo m_optinfo;
 137
 138   static opt_problem *s_the_problem;
 139 };
 140
 141 /* A base class for wrapper classes that track a success/failure value, while
 142    optionally supporting propagating an opt_problem * describing any
 143    failure back up the call stack.  */
 144
 145 template <typename T>
 146 class opt_wrapper
 147 {
 148  public:
 149   typedef T wrapped_t;
 150
 151   /* Be accessible as the wrapped type.  */
 152   operator wrapped_t () const { return m_result; }
 153
 154   /* No public ctor.  */
 155
 156   wrapped_t get_result () const { return m_result; }
 157   opt_problem *get_problem () const { return opt_problem::get_singleton (); }
 158
 159  protected:
 160   opt_wrapper (wrapped_t result, opt_problem */*problem*/)
 161   : m_result (result)
 162   {
 163     /* "problem" is ignored: although it looks like a field, we
 164        actually just use the opt_problem singleton, so that
 165        opt_wrapper<T> in memory is just a T.  */
 166   }
 167
 168  private:
 169   wrapped_t m_result;
 170 };
 171
 172 /* Subclass of opt_wrapper<T> for bool, where
 173    - true signifies "success", and
 174    - false signifies "failure"
 175    whilst effectively propagating an opt_problem * describing any failure
 176    back up the call stack.  */
 177
 178 class opt_result : public opt_wrapper <bool>
 179 {
 180  public:
 181   /* Generate a "success" value: a wrapper around "true".  */
 182
 183   static opt_result success () { return opt_result (true, NULL); }
 184
 185   /* Generate a "failure" value: a wrapper around "false", and,
 186      if dump_enabled_p, an opt_problem.  */
 187
 188   static opt_result failure_at (const dump_location_t &loc,
 189                                 const char *fmt, ...)
 190           ATTRIBUTE_GCC_DUMP_PRINTF (2, 3)
 191   {
 192     opt_problem *problem = NULL;
 193     if (dump_enabled_p ())
 194       {
 195         va_list ap;
 196         va_start (ap, fmt);
 197         problem = new opt_problem (loc, fmt, &ap);
 198         va_end (ap);
 199       }
 200     return opt_result (false, problem);
 201   }
 202
 203   /* Given a failure wrapper of some other kind, make an opt_result failure
 204      object, for propagating the opt_problem up the call stack.  */
 205
 206   template <typename S>
 207   static opt_result
 208   propagate_failure (opt_wrapper <S> other)
 209   {
 210     return opt_result (false, other.get_problem ());
 211   }
 212
 213  private:
 214   /* Private ctor.  Instances should be created by the success and failure
 215      static member functions.  */
 216   opt_result (wrapped_t result, opt_problem *problem)
 217   : opt_wrapper <bool> (result, problem)
 218   {}
 219 };
 220
 221 /* Subclass of opt_wrapper<T> where T is a pointer type, for tracking
 222    success/failure, where:
 223    - a non-NULL value signifies "success", and
 224    - a NULL value signifies "failure",
 225    whilst effectively propagating an opt_problem * describing any failure
 226    back up the call stack.  */
 227
 228 template <typename PtrType_t>
 229 class opt_pointer_wrapper : public opt_wrapper <PtrType_t>
 230 {
 231  public:
 232   typedef PtrType_t wrapped_pointer_t;
 233
 234   /* Given a non-NULL pointer, make a success object wrapping it.  */
 235
 236   static opt_pointer_wrapper <wrapped_pointer_t>
 237   success (wrapped_pointer_t ptr)
 238   {
 239     return opt_pointer_wrapper <wrapped_pointer_t> (ptr, NULL);
 240   }
 241
 242   /* Make a NULL pointer failure object, with the given message
 243      (if dump_enabled_p).  */
 244
 245   static opt_pointer_wrapper <wrapped_pointer_t>
 246   failure_at (const dump_location_t &loc,
 247               const char *fmt, ...)
 248     ATTRIBUTE_GCC_DUMP_PRINTF (2, 3)
 249   {
 250     opt_problem *problem = NULL;
 251     if (dump_enabled_p ())
 252       {
 253         va_list ap;
 254         va_start (ap, fmt);
 255         problem = new opt_problem (loc, fmt, &ap);
 256         va_end (ap);
 257       }
 258     return opt_pointer_wrapper <wrapped_pointer_t> (NULL, problem);
 259   }
 260
 261   /* Given a failure wrapper of some other kind, make a NULL pointer
 262      failure object, propagating the problem.  */
 263
 264   template <typename S>
 265   static opt_pointer_wrapper <wrapped_pointer_t>
 266   propagate_failure (opt_wrapper <S> other)
 267   {
 268     return opt_pointer_wrapper <wrapped_pointer_t> (NULL,
 269                                                     other.get_problem ());
 270   }
 271
 272   /* Support accessing the underlying pointer via ->.  */
 273
 274   wrapped_pointer_t operator-> () const { return this->get_result (); }
 275
 276  private:
 277   /* Private ctor.  Instances should be built using the static member
 278      functions "success" and "failure".  */
 279   opt_pointer_wrapper (wrapped_pointer_t result, opt_problem *problem)
 280   : opt_wrapper<PtrType_t> (result, problem)
 281   {}
 282 };
 283
 284 /* A typedef for wrapping "tree" so that NULL_TREE can carry an
 285    opt_problem describing the failure (if dump_enabled_p).  */
 286
 287 typedef opt_pointer_wrapper<tree> opt_tree;
 288
 289 #endif /* #ifndef GCC_OPT_PROBLEM_H */