Audacity 3.2.0
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  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)>
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.

22{
23 Internal,
26};
@ BadEnvironment
Indicates problems with environment, such as a full disk.
@ BadUserAction
Indicates that the user performed an action that is not allowed.
@ Internal
Indicates internal failure from Audacity.

Function Documentation

◆ DefaultDelayedHandlerAction()

void DefaultDelayedHandlerAction ( AudacityException pException)
inline

A default template parameter for GuardedCall.

Definition at line 123 of file AudacityException.h.

124{
125 if ( pException )
126 pException->DelayedHandlerAction();
127}
virtual void DelayedHandlerAction()=0
Action to do in the main thread at idle time of the event loop.

Referenced by AudioIO::DrainRecordBuffers().

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
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
Exceptions
nothing,whenhandler throws nothing and delayedHandler is defaulted
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 207 of file AudacityException.h.

217 {std::move(delayedHandler)} ) )
218{
219 try { return body(); }
220 catch ( AudacityException &e ) {
221 #ifndef UNCAUGHT_EXCEPTIONS_UNAVAILABLE
222 const auto uncaughtExceptionsCount = std::uncaught_exceptions();
223 #endif
224 auto end = finally( [&]()
225 noexcept(noexcept(
226 std::function<void(AudacityException*)>{
227 std::move(delayedHandler)} )) {
228 // At this point, e is the "current" exception, but not "uncaught"
229 // unless it was rethrown by handler. handler might also throw some
230 // other exception object.
231 #ifdef UNCAUGHT_EXCEPTIONS_UNAVAILABLE
232 if (!std::uncaught_exception()) {
233 #else
234 if (uncaughtExceptionsCount >= std::uncaught_exceptions()) {
235 #endif
236 auto pException = std::current_exception(); // This points to e
238 pException, std::move(delayedHandler));
239 }
240 });
241
242 return handler( &e );
243 }
244 catch ( ... ) {
245 return handler( nullptr );
246 }
247}
Base class for exceptions specially processed by the application.
static void EnqueueAction(std::exception_ptr pException, std::function< void(AudacityException *)> delayedHandler)
auto end(const Ptr< Type, BaseDeleter > &p)
Enables range-for.
Definition: PackedArray.h:159

Referenced by MacroCommands::ApplyMacro(), DBConnection::CheckpointThread(), AudioIO::DrainRecordBuffers(), ExportPCM::Export(), FFmpegPresets::ExportPresets(), AUPImportFileHandle::HandleImport(), KeyConfigPrefs::OnExport(), ExportMultipleDialog::OnExport(), TagsEditorDialog::OnSave(), 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 ( )
inlinenoexcept

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

Definition at line 172 of file AudacityException.h.

172{ return {}; }

◆ MakeSimpleGuard() [2/2]

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

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

Definition at line 167 of file AudacityException.h.

168 { value } ))
169 { return SimpleGuard< R >{ value }; }
A default template parameter for GuardedCall<R>

Referenced by MP3ImportFileHandle::error_cb(), ExecCallback(), MP3ImportFileHandle::filter_cb(), GStreamerNewSample(), MP3ImportFileHandle::input_cb(), MP3ImportFileHandle::output_cb(), and NyquistEffect::PutCallback().

Here is the caller graph for this function: