| AngelScript |

C++ exceptions and longjmp

# Exceptions

Application functions and class methods registered with the script engine are allowed to throw C++ exceptions. The virtual machine will automatically catch any C++ exception, abort the script execution, and return control to the application.

asIScriptContext *ctx = engine->CreateContext();
ctx->Prepare(engine->GetModule("test")->GetFunctionByName("func"));
int r = ctx->Execute();
if( r == asEXECUTION_EXCEPTION )
{
string err = ctx->GetExceptionString();
if( err == "Caught an exception from the application" )
{
// An application function threw an exception while being invoked from the script
...
}
}

By default the VM has no way of distinguishing between different types of exceptions and will just give a standard exception string for all of them. If desired a callback can be registered with the engine to provide a translation of the exception type to a more informative exception string.

void TranslateException(asIScriptContext *ctx, void* /*userParam*/)
{
try
{
// Retrow the original exception so we can catch it again
throw;
}
catch( std::exception &e )
{
// Tell the VM the type of exception that occurred
ctx->SetException(e.what());
}
catch(...)
{
// The callback must not allow any exception to be thrown, but it is not necessary
// to explicitly set an exception string if the default exception string is sufficient
}
}
// Register the callback with the engine
engine->SetTranslateAppExceptionCallback(asFUNCTION(TranslateException), 0, asCALL_CDECL);

See also
  GetExceptionInfo helper function

Note
  The ability to catch exceptions can be turned off by compiling the library with the AS_NO_EXCEPTIONS defined. If this is done, the application should not register any functions that may throw exceptions, as the end result will be undefined should an exception occur.

# longjmp

Some applications uses longjmp to do error handling. When performing a longjmp to a previously saved state, there is no chance for the code to do a cleanup of all that happened after the saved state. Because of that the application must not register functions that can perform a longjmp out from the function, as that can leave the virtual machine in an undefined state.

asIScriptContext
The interface to the virtual machine.
Definition: angelscript.h:2717
asIScriptEngine::GetModule
virtual asIScriptModule * GetModule(const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0
Return an interface pointer to the module.
asIScriptContext::Execute
virtual int Execute()=0
Executes the prepared function.
asEXECUTION_EXCEPTION
@ asEXECUTION_EXCEPTION
The execution was terminated by an unhandled script exception.
Definition: angelscript.h:404
asIScriptContext::GetExceptionString
virtual const char * GetExceptionString()=0
Returns the exception string text.
asIScriptModule::GetFunctionByName
virtual asIScriptFunction * GetFunctionByName(const char *name) const =0
Returns the function by its name.
asFUNCTION
#define asFUNCTION(f)
Returns an asSFuncPtr representing the function specified by the name.
Definition: angelscript.h:675
asIScriptEngine::CreateContext
virtual asIScriptContext * CreateContext()=0
Creates a new script context.
asIScriptEngine::SetTranslateAppExceptionCallback
virtual int SetTranslateAppExceptionCallback(asSFuncPtr callback, void *param, int callConv)=0
Register the exception translation callback.
asIScriptContext::SetException
virtual int SetException(const char *info, bool allowCatch=true)=0
Sets an exception, which aborts the execution.
asCALL_CDECL
@ asCALL_CDECL
A cdecl function.
Definition: angelscript.h:226
asIScriptContext::Prepare
virtual int Prepare(asIScriptFunction *func)=0
Prepares the context for execution of the function.