Freespace2 Open 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-needs-\n ); |
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-needs-\n ); |
No |
- 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 |
- 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 for 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
- I believe 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
|
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 exceptional handling scheme.
