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	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 class	ExceptionType { Internal , BadUserAction , BadEnvironment }
	A type of an exception. More...

Functions
void	DefaultDelayedHandlerAction (AudacityException *pException)
	A default template parameter for GuardedCall. More...
template<typename R >
SimpleGuard< R >	MakeSimpleGuard (R value) noexcept(noexcept(SimpleGuard< R >{ value }))
	Convert a value to a handler function returning that value, suitable for GuardedCall<R> More...
SimpleGuard< void >	MakeSimpleGuard () noexcept
	Convert a value to a no-op handler function, suitable for GuardedCall<void> More...
template<typename R = void, typename F1 , typename F2 = SimpleGuard< R >, typename F3 = void (*)(AudacityException *pException)>
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. 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 class 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.

{
    Internal, 
    BadUserAction, 
    BadEnvironment, 
};

Function Documentation

DefaultDelayedHandlerAction()

void DefaultDelayedHandlerAction ( AudacityException *  pException )

inline

A default template parameter for GuardedCall.

Definition at line 123 of file AudacityException.h.

{
   if ( pException )
      pException->DelayedHandlerAction();
}

References AudacityException::DelayedHandlerAction().

Referenced by AudioIO::DrainRecordBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

GuardedCall()

template<typename R = void, typename F1 , typename F2 = SimpleGuard< R >, typename F3 = void (*)(AudacityException *pException)>

R GuardedCall ( const F1 &  body, const F2 &  handler = F2::Default(), F3  delayedHandler = DefaultDelayedHandlerAction  )

noexcept

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

R	Return type, defaulted to void, or else the only explicit template parameter
F1	deduced type of body function; takes no arguments, returns R
F2	deduced 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
F3	deduced type of delayed handler function, if a nondefault argument is given; takes pointer to AudacityException, return value is unused

Exceptions

nothing,when

handler throws nothing and delayedHandler is defaulted

Parameters

body	typically a lambda
handler	default just returns false or void; see also MakeSimpleGuard
delayedHandler	called later in the main thread, passing it a stored exception; usually defaulted

Definition at line 207 of file AudacityException.h.

                                           {std::move(delayedHandler)} ) )
{
   try { return body(); }
   catch ( AudacityException &e ) {
   #ifndef UNCAUGHT_EXCEPTIONS_UNAVAILABLE
      const auto uncaughtExceptionsCount = std::uncaught_exceptions();
   #endif  
      auto end = finally( [&]()
      noexcept(noexcept(
         std::function<void(AudacityException*)>{
            std::move(delayedHandler)} )) {
         // At this point, e is the "current" exception, but not "uncaught"
         // unless it was rethrown by handler.  handler might also throw some
         // other exception object.
      #ifdef UNCAUGHT_EXCEPTIONS_UNAVAILABLE
         if (!std::uncaught_exception()) {
      #else         
         if (uncaughtExceptionsCount >= std::uncaught_exceptions()) {
      #endif      
            auto pException = std::current_exception(); // This points to e
            AudacityException::EnqueueAction(
               pException, std::move(delayedHandler));
         }
      });
 
      return handler( &e );
   }
   catch ( ... ) {
      return handler( nullptr );
   }
}

Referenced by MacroCommands::ApplyMacro(), DBConnection::CheckpointThread(), AudioIO::DrainRecordBuffers(), FFmpegPresets::ExportPresets(), AUPImportFileHandle::HandleImport(), KeyConfigPrefs::OnExport(), TagsEditorDialog::OnSave(), PCMExportProcessor::Process(), ProjectFSCK(), EQCurveWriter::SaveCurves(), AudioIO::StopStream(), FFmpegPresets::~FFmpegPresets(), SqliteSampleBlock::~SqliteSampleBlock(), and XMLFileWriter::~XMLFileWriter().

Here is the caller graph for this function:

MakeSimpleGuard() [1/2]

SimpleGuard< void > MakeSimpleGuard ( )

inlinenoexcept

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

Definition at line 172 of file AudacityException.h.

{ return {}; }

MakeSimpleGuard() [2/2]

template<typename R >

SimpleGuard< R > MakeSimpleGuard ( R  value )

noexcept

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

Definition at line 167 of file AudacityException.h.

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

Referenced by ExecCallback(), and NyquistBase::NyxContext::PutCallback().

Here is the caller graph for this function: