Difference between revisions of "FSO Error Handling"

From FreeSpace Wiki
Jump to: navigation, search
(General)
m (formatting and category added)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Freespace2 Open Error Handling ==
 
 
 
{{note | Needs more details! }}
 
{{note | Needs more details! }}
  
 
This is meant to assist coders in figuring out how errors in FSO should be handled.
 
This is meant to assist coders in figuring out how errors in FSO should be handled.
  
=== General ===
+
== General ==
  
 
There are several macros defined for error handling (see globalincs/pstypes.h).
 
There are several macros defined for error handling (see globalincs/pstypes.h).
Line 26: Line 24:
 
* Used for verbose logging that would otherwise clog up the fs2_open.log  
 
* Used for verbose logging that would otherwise clog up the fs2_open.log  
 
|-
 
|-
| Warning( LOCATION, printf-formatted-message-needs-\n ); || No ||  
+
| Warning( LOCATION, printf-formatted-message ); || No ||  
 
* Something has gone wrong, but either it's recoverable or it may not be critical.
 
* Something has gone wrong, but either it's recoverable or it may not be critical.
 
* FSO continues to execute.
 
* FSO continues to execute.
Line 33: Line 31:
 
* The 1st argument, LOCATION is required verbatim
 
* The 1st argument, LOCATION is required verbatim
 
|-
 
|-
| WarningEx( LOCATION, printf-formatted-message-needs-\n ); || No ||
+
| WarningEx( LOCATION, printf-formatted-message ); || No ||
 
* Same as warning, except it will only trigger if the command line param "-extra_warn" is set
 
* Same as warning, except it will only trigger if the command line param "-extra_warn" is set
 
|-
 
|-
| Error( LOCATION, printf-formatted-message-needs-\n );  || Yes ||
+
| Error( LOCATION, printf-formatted-message );  || Yes ||
 
* Something has gone horribly wrong and it's not "safe" to continue.
 
* Something has gone horribly wrong and it's not "safe" to continue.
 
* FSO exits.
 
* FSO exits.
Line 52: Line 50:
 
|-
 
|-
 
| Verify( ??? ); || Yes ||
 
| Verify( ??? ); || Yes ||
* Like an Assert (??) , but for Release & Debug
+
* Like an Assert, but works in both Release & Debug
 
|-
 
|-
 
| VerifyEx( ??? ); || Yes ||
 
| VerifyEx( ??? ); || Yes ||
Line 59: Line 57:
 
| Int3(); || No ||
 
| Int3(); || No ||
 
* very old, don't add any more of these to FSO
 
* very old, don't add any more of these to FSO
* I believe on Windows it stops execution and gives a coder the chance to attach a debugger
+
* On Windows it stops execution and gives a coder the chance to attach a debugger
* On other platforms I believe it acts like an Error
+
* On other platforms it acts like an Error
 
|}
 
|}
  
=== LUA Scripting ===
+
== LUA Scripting ==
  
 
While all the FSO error handling can be used in LUA, it's preferred to use the following where possible.
 
While all the FSO error handling can be used in LUA, it's preferred to use the following where possible.
Line 84: Line 82:
  
  
=== Table Parsing ===
+
== Table Parsing ==
  
 
tbc
 
tbc
Line 90: Line 88:
  
  
=== C++ Exceptions ===
+
== 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.
  
Exceptions are relatively rare in FSO (see pilotcode for one exception (hardy-har-har)), I don't believe there's any formal exceptional handling scheme.
+
[[Category:Source Code Project]]

Latest revision as of 11:59, 14 September 2021

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.