Description

"Static" class responsible for error registration and throwing

ErrorManager holds a map with all errors that may be thrown from paclet code. These are: LLU errors, framework errors (e.g. MDevices) and paclet-specific errors which should be registered (for example in WolframLibrary_initialize) using registerPacletErrors function. Developers must never throw LibraryLinkErrors directly, instead they should use one of ErrorManager::throwException overloads.

#include <ErrorManager.h>

Public Types
using	ErrorStringData = std::pair< std::string, std::string >
	A type representing registered error in the form of 2 strings: short error name and longer error description. More...

Public Member Functions
	ErrorManager ()=delete
	Default constructor is deleted since ErrorManager is supposed to be completely static. More...

Static Public Member Functions
static void	registerPacletErrors (const std::vector< ErrorStringData > &errors)
	Function used to register paclet-specific errors. More...

template<typename... T>
static void	throwException (const std::string &errorName, T &&... args)
	Throw exception with given name. More...

template<typename... T>
static void	throwException (WolframLibraryData libData, const std::string &errorName, T &&... args)
	Throw exception with given name. More...

template<class Error , typename... Args>
static void	throwCustomException (const std::string &errorName, Args &&... args)
	Throw exception of given class that carries the error with given name. More...

template<typename... T>
static void	throwExceptionWithDebugInfo (const std::string &errorName, const std::string &debugInfo, T &&... args)
	Throw exception with given name and additional information that might be helpful in debugging. More...

template<typename... T>
static void	throwExceptionWithDebugInfo (WolframLibraryData libData, const std::string &errorName, const std::string &debugInfo, T &&... args)
	Throw exception with given name and additional information that might be helpful in debugging. More...

static void	setSendParametersImmediately (bool newValue)
	Sets new value for the sendParametersImmediately flag. More...

static bool	getSendParametersImmediately ()
	Get the current value of sendParametersImmediately flag. More...

static void	sendRegisteredErrorsViaWSTP (WSLINK mlp)
	Function used to send all registered errors to top-level Mathematica code. More...

Type aliases documentation

◆ ErrorStringData

using LLU::ErrorManager::ErrorStringData = std::pair<std::string, std::string>

A type representing registered error in the form of 2 strings: short error name and longer error description.

Constructor & Destructor Documentation

◆ ErrorManager()

LLU::ErrorManager::ErrorManager ( )

delete

Default constructor is deleted since ErrorManager is supposed to be completely static.

Member Function Documentation

◆ getSendParametersImmediately()

static bool LLU::ErrorManager::getSendParametersImmediately ( )

inlinestatic

Get the current value of sendParametersImmediately flag.

Returns: current value of sendParametersImmediately flag.

◆ registerPacletErrors()

void LLU::ErrorManager::registerPacletErrors ( const std::vector< ErrorStringData > & errors )

static

Function used to register paclet-specific errors.

Parameters

errors - a list of pairs: {"ErrorName", "Short string with error description"}

◆ sendRegisteredErrorsViaWSTP()

void LLU::ErrorManager::sendRegisteredErrorsViaWSTP ( WSLINK mlp )

static

Function used to send all registered errors to top-level Mathematica code.

Sending registered errors allows for nice and meaningful Failure objects to be generated when paclet function fails in top level, instead of usual LibraryFunctionError expressions.

Parameters

mlp	- active WSTP connection

◆ setSendParametersImmediately()

static void LLU::ErrorManager::setSendParametersImmediately ( bool newValue )

inlinestatic

Sets new value for the sendParametersImmediately flag.

Pass false to make sure that exception do not send their parameters to top-level when they are thrown. This is essential in multithreaded applications since the WL symbol that parameters are assigned to may be treated as a global shared resource. It is recommended to use this method in WolframLibrary_initialize.

Parameters

newValue - new value for the sendParametersImmediately flag

◆ throwCustomException()

template<class Error , typename... Args>

void LLU::ErrorManager::throwCustomException	(	const std::string &	errorName,
		Args &&...	args
	)

static

Throw exception of given class that carries the error with given name.

This is useful if you want to throw custom exception classes from your paclet and still see the nice Failure objects in top-level.

Template Parameters

Error - custom exception class it must define a constructor that takes a LibraryLinkError as first parameter but it doesn't have to derive from LibraryLinkError

Parameters

errorName	- name of error to be thrown
args	- additional arguments that will be perfectly forwarded to the constructor of Error class

◆ throwException() [1/2]

template<typename... T>

void LLU::ErrorManager::throwException	(	const std::string &	errorName,
		T &&...	args
	)

static

Throw exception with given name.

Optionally, pass arbitrary details of the exception occurrence and they will be stored on a loopback link in the exception object. Those details may later be sent via WSTP to top-level and assigned as a List to to the symbol specified in ErrorManager::exceptionDetailsSymbol. To trigger exception details transfer one should call LibraryLinkError::sendParameters on the exception object. However, if ErrorManager::sendParametersImmediately is set to true, this call will be done automatically in throwException.

Template Parameters

T	- type template parameter pack

Parameters

errorName	- name of error to be thrown, must be registered beforehand
args	- any number of arguments that will replace TemplateSlots (``,`1`,`xx`, etd) in the message text in top-level

Note: This function requires a copy of WolframLibraryData to be saved in WolframLibrary_initialize via LibraryData::setLibraryData or MArgumentManager::setLibraryData.

◆ throwException() [2/2]

template<typename... T>

void LLU::ErrorManager::throwException	(	WolframLibraryData	libData,
		const std::string &	errorName,
		T &&...	args
	)

static

Throw exception with given name.

Optionally, pass arbitrary details of the exception occurrence and they will be stored on a loopback link in the exception object. Those details may later be sent via WSTP to top-level and assigned as a List to to the symbol specified in ErrorManager::exceptionDetailsSymbol. To trigger exception details transfer one should call LibraryLinkError::sendParameters on the exception object. However, if ErrorManager::sendParametersImmediately is set to true, this call will be done automatically in throwException.

Template Parameters

T	- type template parameter pack

Parameters

libData	- a copy of WolframLibraryData which should be used to extract the WSLINK for WSTP connection
errorName	- name of error to be thrown, must be registered beforehand
args	- any number of arguments that will replace TemplateSlots (``,`1`,`xx`, etd) in the message text in top-level

◆ throwExceptionWithDebugInfo() [1/2]

template<typename... T>

void LLU::ErrorManager::throwExceptionWithDebugInfo	(	const std::string &	errorName,
		const std::string &	debugInfo,
		T &&...	args
	)

static

Throw exception with given name and additional information that might be helpful in debugging.

Optionally, pass arbitrary details of the exception occurrence and they will be stored on a loopback link in the exception object. Those details may later be sent via WSTP to top-level and assigned as a List to to the symbol specified in ErrorManager::exceptionDetailsSymbol. To trigger exception details transfer one should call LibraryLinkError::sendParameters on the exception object. However, if ErrorManager::sendParametersImmediately is set to true, this call will be done automatically in throwException. The debugInfo is a string stored inside the LibraryLinkError object. It is never transferred to top-level but might be for example logged to a file in a "catch" block in C++ code.

Template Parameters

T	- type template parameter pack

Parameters

errorName	- name of error to be thrown, must be registered beforehand
debugInfo	- additional message with debug info, this message will not be passed to top-level Failure object
args	- any number of arguments that will replace TemplateSlots (``,`1`,`xx`, etd) in the message text in top-level

Note: This function requires a copy of WolframLibraryData to be saved in WolframLibrary_initialize via LibraryData::setLibraryData or MArgumentManager::setLibraryData.

◆ throwExceptionWithDebugInfo() [2/2]

template<typename... T>

void LLU::ErrorManager::throwExceptionWithDebugInfo	(	WolframLibraryData	libData,
		const std::string &	errorName,
		const std::string &	debugInfo,
		T &&...	args
	)

static

Throw exception with given name and additional information that might be helpful in debugging.

Optionally, pass arbitrary details of the exception occurrence and they will be stored on a loopback link in the exception object. Those details may later be sent via WSTP to top-level and assigned as a List to to the symbol specified in ErrorManager::exceptionDetailsSymbol. To trigger exception details transfer one should call LibraryLinkError::sendParameters on the exception object. However, if ErrorManager::sendParametersImmediately is set to true, this call will be done automatically in throwException. The debugInfo is a string stored inside the LibraryLinkError object. It is never transferred to top-level but might be for example logged to a file in a "catch" block in C++ code.

Template Parameters

T	- type template parameter pack

Parameters

libData	- a copy of WolframLibraryData which should be used to extract the WSLINK for WSTP connection
errorName	- name of error to be thrown, must be registered beforehand
debugInfo	- additional message with debug info, this message will not be passed to top-level Failure object
args	- any number of arguments that will replace TemplateSlots (``,`1`,`xx`, etd) in the message text in top-level

Description

Public Types

Public Member Functions

Static Public Member Functions

Type aliases documentation

◆ ErrorStringData

Constructor & Destructor Documentation

◆ ErrorManager()

Member Function Documentation

◆ getSendParametersImmediately()

◆ registerPacletErrors()

◆ sendRegisteredErrorsViaWSTP()

◆ setSendParametersImmediately()

◆ throwCustomException()

◆ throwException() [1/2]

◆ throwException() [2/2]

◆ throwExceptionWithDebugInfo() [1/2]

◆ throwExceptionWithDebugInfo() [2/2]