Audacity  3.2.0
AudacityException.h
Go to the documentation of this file.
1 #ifndef __AUDACITY_EXCEPTION__
2 #define __AUDACITY_EXCEPTION__
3 
4 /*!********************************************************************
5 
6  Audacity: A Digital Audio Editor
7 
8  @file AudacityException.h
9  @brief Declare abstract class AudacityException, some often-used subclasses, and @ref GuardedCall
10 
11  Paul Licameli
12  **********************************************************************/
13 
14 #include "MemoryX.h"
15 #include <exception>
16 #include <functional>
17 
18 #include "Internat.h"
19 
21 enum class ExceptionType
22 {
23  Internal,
26 };
27 
29 
32 class EXCEPTIONS_API AudacityException /* not final */
33 {
34 public:
36  virtual ~AudacityException() = 0;
37 
39  virtual void DelayedHandlerAction() = 0;
40 
41  static void EnqueueAction(
42  std::exception_ptr pException,
43  std::function<void(AudacityException*)> delayedHandler);
44 
45 protected:
47  AudacityException( const AudacityException& ) = default;
48 
50  // see https://bugzilla.audacityteam.org/show_bug.cgi?id=2442
52 
54  AudacityException &operator = ( const AudacityException & ) PROHIBITED;
55 };
56 
58 
60 class EXCEPTIONS_API MessageBoxException /* not final */
61  : public AudacityException
62 {
65 
67  void DelayedHandlerAction() final;
68 
69 protected:
71  explicit MessageBoxException(
72  ExceptionType exceptionType,
73  const TranslatableString &caption
74  );
75  ~MessageBoxException() override;
76 
78 
80  virtual TranslatableString ErrorMessage() const = 0;
81  virtual wxString ErrorHelpUrl() const { return helpUrl; };
82 
83 private:
86 
87  mutable bool moved { false };
88 protected:
89  mutable wxString helpUrl{ "" };
90 };
91 
93 class EXCEPTIONS_API SimpleMessageBoxException /* not final */
94  : public MessageBoxException
95 {
96 public:
98  ExceptionType exceptionType,
99  const TranslatableString &message_, //<! Message to show
100  const TranslatableString &caption = XO("Message"), //<! Short caption in frame around message
101  const wxString &helpUrl_ = "" // Optional URL for help.
102  )
103  : MessageBoxException { exceptionType, caption }
104  , message{ message_ }
105  {
106  helpUrl = helpUrl_;
107  }
108  ~SimpleMessageBoxException() override;
109 
112  SimpleMessageBoxException && ) PROHIBITED;
113 
114  // Format a default, internationalized error message for this exception.
115  virtual TranslatableString ErrorMessage() const override;
116 
117 private:
119 };
120 
121 
124 {
125  if ( pException )
126  pException->DelayedHandlerAction();
127 }
128 
130 
131 template <typename R> struct SimpleGuard
132 {
133  explicit SimpleGuard(
134  const R &value
135  )
136  noexcept(noexcept( R{ std::declval<const R&>() } ))
137  : m_value{ value } {}
138  R operator () ( AudacityException * ) const
139  noexcept(noexcept( R{ std::declval<R>() } ))
140  { return m_value; }
141  const R m_value;
142 };
143 
145 template<> struct SimpleGuard<bool>
146 {
147  explicit SimpleGuard(
148  bool value
149  ) noexcept
150  : m_value{ value } {}
151  bool operator () ( AudacityException * ) const noexcept { return m_value; }
152  static SimpleGuard Default() noexcept
153  { return SimpleGuard{ false }; }
154  const bool m_value;
155 };
156 
158 template<> struct SimpleGuard<void>
159 {
160  SimpleGuard() noexcept {}
161  void operator () ( AudacityException * ) const noexcept {}
162  static SimpleGuard Default() noexcept { return {}; }
163 };
164 
166 template < typename R >
168  noexcept(noexcept( SimpleGuard< R >{ value } ))
169  { return SimpleGuard< R >{ value }; }
170 
172 inline SimpleGuard< void > MakeSimpleGuard() noexcept { return {}; }
173 
196 template <
197  typename R = void,
198 
199  typename F1, // function object with signature R()
200 
201  typename F2 = SimpleGuard< R >, // function object
202  // with signature R( AudacityException * )
203 
204  typename F3 = void (*)(AudacityException *pException)
205 >
208  const F1 &body,
209  const F2 &handler = F2::Default(),
210  F3 delayedHandler = DefaultDelayedHandlerAction
212 )
213 noexcept(
214  noexcept( handler( std::declval<AudacityException*>() ) ) &&
215  noexcept( handler( nullptr ) ) &&
216  noexcept(
217  std::function<void(AudacityException*)>{std::move(delayedHandler)} ) )
218 {
219  try { return body(); }
220  catch ( AudacityException &e ) {
221 
222  auto end = finally( [&]()
223  noexcept(noexcept(
224  std::function<void(AudacityException*)>{
225  std::move(delayedHandler)} )) {
226  // At this point, e is the "current" exception, but not "uncaught"
227  // unless it was rethrown by handler. handler might also throw some
228  // other exception object.
229  if (!std::uncaught_exception()) {
230  auto pException = std::current_exception(); // This points to e
232  pException, std::move(delayedHandler));
233  }
234  });
235 
236  return handler( &e );
237  }
238  catch ( ... ) {
239  return handler( nullptr );
240  }
241 }
242 
243 #endif
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
SimpleGuard
A default template parameter for GuardedCall<R>
Definition: AudacityException.h:132
SimpleGuard< bool >::SimpleGuard
SimpleGuard(bool value) noexcept
Definition: AudacityException.h:147
ExceptionType
ExceptionType
A type of an exception.
Definition: AudacityException.h:22
MessageBoxException::exceptionType
ExceptionType exceptionType
Exception type.
Definition: AudacityException.h:85
ExceptionType::BadEnvironment
@ BadEnvironment
Indicates problems with environment, such as a full disk.
XO
#define XO(s)
Definition: Internat.h:31
SimpleGuard::m_value
const R m_value
Definition: AudacityException.h:141
SimpleGuard< bool >::m_value
const bool m_value
Definition: AudacityException.h:154
SimpleMessageBoxException::SimpleMessageBoxException
SimpleMessageBoxException(ExceptionType exceptionType, const TranslatableString &message_, const TranslatableString &caption=XO("Message"), const wxString &helpUrl_="")
Definition: AudacityException.h:97
AudacityException::EnqueueAction
static void EnqueueAction(std::exception_ptr pException, std::function< void(AudacityException *)> delayedHandler)
Definition: AudacityException.cpp:22
AudacityException::AudacityException
AudacityException(const AudacityException &)=default
Make this protected to prevent slicing copies.
MessageBoxException::ErrorHelpUrl
virtual wxString ErrorHelpUrl() const
Definition: AudacityException.h:81
DefaultDelayedHandlerAction
void DefaultDelayedHandlerAction(AudacityException *pException)
A default template parameter for GuardedCall.
Definition: AudacityException.h:123
MessageBoxException::ErrorMessage
virtual TranslatableString ErrorMessage() const =0
Format the error message for this exception.
AudacityException
Base class for exceptions specially processed by the application.
Definition: AudacityException.h:33
SimpleGuard< void >::SimpleGuard
SimpleGuard() noexcept
Definition: AudacityException.h:160
AudacityException::AudacityException
AudacityException()
Definition: AudacityException.h:35
SimpleGuard< void >::Default
static SimpleGuard Default() noexcept
Definition: AudacityException.h:162
Internat.h
AudacityException::AudacityException
AudacityException(AudacityException &&) PROHIBITED
Don't allow moves of this class or subclasses.
SimpleGuard< void >
Specialization of SimpleGuard, also defining a default value.
Definition: AudacityException.h:159
MemoryX.h
SimpleGuard::SimpleGuard
SimpleGuard(const R &value) noexcept(noexcept(R{ std::declval< const R & >() }))
Definition: AudacityException.h:133
AudacityException::DelayedHandlerAction
virtual void DelayedHandlerAction()=0
Action to do in the main thread at idle time of the event loop.
MessageBoxException
Abstract AudacityException subclass displays a message, specified by further subclass.
Definition: AudacityException.h:62
MakeSimpleGuard
SimpleGuard< R > MakeSimpleGuard(R value) noexcept(noexcept(SimpleGuard< R >{ value }))
Convert a value to a handler function returning that value, suitable for GuardedCall<R>
Definition: AudacityException.h:167
ExceptionType::Internal
@ Internal
Indicates internal failure from Audacity.
AudacityException::operator=
AudacityException & operator=(const AudacityException &) PROHIBITED
Disallow assignment.
GuardedCall
R GuardedCall(const F1 &body, const F2 &handler=F2::Default(), F3 delayedHandler=DefaultDelayedHandlerAction) noexcept(noexcept(handler(std::declval< AudacityException * >())) &&noexcept(handler(nullptr)) &&noexcept(std::function< void(AudacityException *)>{std::move(delayedHandler)}))
Execute some code on any thread; catch any AudacityException; enqueue error report on the main thread...
Definition: AudacityException.h:207
SimpleMessageBoxException::SimpleMessageBoxException
SimpleMessageBoxException(const SimpleMessageBoxException &)=default
ExceptionType::BadUserAction
@ BadUserAction
Indicates that the user performed an action that is not allowed.
SimpleGuard< bool >::Default
static SimpleGuard Default() noexcept
Definition: AudacityException.h:152
SimpleMessageBoxException
A MessageBoxException that shows a given, unvarying string.
Definition: AudacityException.h:95
MessageBoxException::caption
TranslatableString caption
Stored caption.
Definition: AudacityException.h:81