FSO Error Handling

Note: Needs more details!

This is meant to assist coders in figuring out how errors in FSO should be handled.

General

There are several macros defined for error handling (see globalincs/pstypes.h).

One of the 1st concepts to understand is that some errors in trigger in DEBUG builds, others occur in both DEBUG and RELEASE.

Most of these can be used anywhere within the FSO codebase.

Name	In Release?	Description
mprintf(( printf-formatted-message-needs-\n ));	No	Prints text to fs2_open.log Generally used for issues that a modder/coder should know about, but not a player Warning: Dynamically allocates memory (SCP_string) so don't use it inside memory management functions
nprintf(( TYPE, printf-formatted-message-needs-\n ));	No	Like mprintf, but output is conditional on TYPE being selected in a debug_filter.cfg Used for verbose logging that would otherwise clog up the fs2_open.log
Warning( LOCATION, printf-formatted-message );	No	Something has gone wrong, but either it's recoverable or it may not be critical. FSO continues to execute. On Windows, pops up a message box that must be closed by the player. Generally should be used for asset issues not coding issues. The 1st argument, LOCATION is required verbatim
WarningEx( LOCATION, printf-formatted-message );	No	Same as warning, except it will only trigger if the command line param "-extra_warn" is set
Error( LOCATION, printf-formatted-message );	Yes	Something has gone horribly wrong and it's not "safe" to continue. FSO exits. On Windows, outputs a stack trace (symbol may/may not be present depending on how FSO was compiled... I think...) Generally should be used for asset issues not coding issues. The 1st argument, LOCATION is required verbatim
Assert( statement );	No	Require that a statement be true Generally used to catch coding errors (e.g. input pointers are not-NULL) Not recommended because the output is very terse, use Assertion where-ever possible instead
Assertion( statement, printf-formatted-message-needs-\n );	No	Same as Assert, except more verbose & *recommended*
Verify( ??? );	Yes	Like an Assert, but works in both Release & Debug
VerifyEx( ??? );	Yes	Same as Verify, except it will only trigger if the command line param "-extra_warn" is set
Int3();	No	very old, don't add any more of these to FSO On Windows it stops execution and gives a coder the chance to attach a debugger On other platforms it acts like an Error

LUA Scripting

While all the FSO error handling can be used in LUA, it's preferred to use the following where possible.

In parse/lua.cpp.

Name	In Release?	Description
LuaError( LuaObject, printf-formatted-message );	?	Like a general Error, but for LUA FSO exits and prints a LUA stacktrace (doesn't seem to include the calling function, so you should probably add that to the text)
ade_set_error( LuaObject, return-value-type, return-value );	?	Returns an error to the calling LUA script which is expected to deal with to appropriately Some of the return-value-types are "o" (object), "i" (int), "s" (string) - see ade_set_args() for the others FSO doesn't care and continues executing

Table Parsing

tbc (I think there's some extra error handling options in here)

C++ Exceptions

Exceptions are relatively rare in FSO (see pilotcode for one exception (hardy-har-har)), I don't believe there's any formal exception handling scheme.