Audacity  3.0.3
Classes | Enumerations | Functions
AudacityException.h File Reference

Declare abstract class AudacityException, some often-used subclasses, and GuardedCall. More...

#include "MemoryX.h"
#include <exception>
#include <functional>
#include "Internat.h"
Include dependency graph for AudacityException.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  AudacityException
 Base class for exceptions specially processed by the application. More...
 
class  MessageBoxException
 Abstract AudacityException subclass displays a message, specified by further subclass. More...
 
class  SimpleMessageBoxException
 A MessageBoxException that shows a given, unvarying string. More...
 
struct  DefaultDelayedHandlerAction
 A default template parameter for GuardedCall. More...
 
struct  SimpleGuard< R >
 A default template parameter for GuardedCall<R> More...
 
struct  SimpleGuard< bool >
 Specialization of SimpleGuard, also defining a default value. More...
 
struct  SimpleGuard< void >
 Specialization of SimpleGuard, also defining a default value. More...
 

Enumerations

enum  ExceptionType { ExceptionType::Internal, ExceptionType::BadUserAction, ExceptionType::BadEnvironment }
 A type of an exception. More...
 

Functions

template<typename R >
SimpleGuard< R > MakeSimpleGuard (R value)
 Convert a value to a handler function returning that value, suitable for GuardedCall<R> More...
 
SimpleGuard< void > MakeSimpleGuard ()
 Convert a value to a no-op handler function, suitable for GuardedCall<void> More...
 
template<typename R = void, typename F1 , typename F2 = SimpleGuard< R >>
GuardedCall (const F1 &body, const F2 &handler=F2::Default(), std::function< void(AudacityException *)> delayedHandler=DefaultDelayedHandlerAction{})
 Execute some code on any thread; catch any AudacityException; enqueue error report on the main thread. More...
 

Detailed Description

Declare abstract class AudacityException, some often-used subclasses, and GuardedCall.


Audacity: A Digital Audio Editor

Paul Licameli

Definition in file AudacityException.h.

Enumeration Type Documentation

◆ ExceptionType

enum ExceptionType
strong

A type of an exception.

Enumerator
Internal 

Indicates internal failure from Audacity.

BadUserAction 

Indicates that the user performed an action that is not allowed.

BadEnvironment 

Indicates problems with environment, such as a full disk.

Definition at line 21 of file AudacityException.h.

22 {
23  Internal,
26 };

Function Documentation

◆ GuardedCall()

template<typename R = void, typename F1 , typename F2 = SimpleGuard< R >>
R GuardedCall ( const F1 &  body,
const F2 &  handler = F2::Default(),
std::function< void(AudacityException *)>  delayedHandler = DefaultDelayedHandlerAction{} 
)

Execute some code on any thread; catch any AudacityException; enqueue error report on the main thread.

Executes a given function (typically a lamba), in any thread.

If there is any exception, can invoke another given function as handler, which may rethrow that or another exception, but usually just returns the value for the GuardedCall.

If AudacityException is handled, then it queues up a delayed handler action for execution later in the event loop at idle time, on the main thread; typically this informs the user of the error.

The default delayed handler action is simply to invoke a method of the AudacityException, but this too can be specified otherwise by a third function.

Template Parameters
RReturn type, defaulted to void, or else the only explicit template parameter
F1deduced type of body function; takes no arguments, returns R
F2deduced type of handler function, or defaulted to SimpleGuard<R>; takes pointer to AudacityException, which is null when some other type of exception is caught; return value is converted to R
F3deduced type of delayed handler function, if a nondefault argument is given; takes pointer to AudacityException, return value is unused
Parameters
bodytypically a lambda
handlerdefault just returns false or void; see also MakeSimpleGuard
delayedHandlercalled later in the main thread, passing it a stored exception; usually defaulted

Definition at line 202 of file AudacityException.h.

206  {}
208 )
209 {
210  try { return body(); }
211  catch ( AudacityException &e ) {
212 
213  auto end = finally([&]{
214  // At this point, e is the "current" exception, but not "uncaught"
215  // unless it was rethrown by handler. handler might also throw some
216  // other exception object.
217  if (!std::uncaught_exception()) {
218  auto pException = std::current_exception(); // This points to e
220  pException, std::move(delayedHandler));
221  }
222  });
223 
224  return handler( &e );
225  }
226  catch ( ... ) {
227  return handler( nullptr );
228  }
229 }

Referenced by MacroCommands::ApplyMacro(), DBConnection::CheckpointThread(), ExportPCM::Export(), FFmpegPresets::ExportPresets(), AudioIO::FillBuffers(), AUPImportFileHandle::HandleImport(), KeyConfigPrefs::OnExport(), ExportMultipleDialog::OnExport(), TagsEditorDialog::OnSave(), Effect::Preview(), ProjectFSCK(), EffectEqualization::SaveCurves(), AudioIO::StopStream(), FFmpegPresets::~FFmpegPresets(), SqliteSampleBlock::~SqliteSampleBlock(), and XMLFileWriter::~XMLFileWriter().

Here is the caller graph for this function:

◆ MakeSimpleGuard() [1/2]

SimpleGuard< void > MakeSimpleGuard ( )
inline

Convert a value to a no-op handler function, suitable for GuardedCall<void>

Definition at line 171 of file AudacityException.h.

171 { return {}; }

◆ MakeSimpleGuard() [2/2]

template<typename R >
SimpleGuard< R > MakeSimpleGuard ( value)

Convert a value to a handler function returning that value, suitable for GuardedCall<R>

Definition at line 167 of file AudacityException.h.

168 { return SimpleGuard< R >{ value }; }

Referenced by MP3ImportFileHandle::ErrorCB(), ExecCallback(), MP3ImportFileHandle::filter_cb(), GStreamerNewSample(), MP3ImportFileHandle::input_cb(), MP3ImportFileHandle::OutputCB(), and NyquistEffect::PutCallback().

Here is the caller graph for this function:
SimpleGuard
A default template parameter for GuardedCall<R>
Definition: AudacityException.h:135
ExceptionType::BadEnvironment
@ BadEnvironment
Indicates problems with environment, such as a full disk.
AudacityException::EnqueueAction
static EXCEPTIONS_API void EnqueueAction(std::exception_ptr pException, std::function< void(AudacityException *)> delayedHandler)
Definition: AudacityException.cpp:22
AudacityException
Base class for exceptions specially processed by the application.
Definition: AudacityException.h:33
ExceptionType::Internal
@ Internal
Indicates internal failure from Audacity.
ExceptionType::BadUserAction
@ BadUserAction
Indicates that the user performed an action that is not allowed.