FSO Error Handling - Revision history

TopAce: formatting and category added

2021-09-14T11:59:48Z

formatting and category added

← Older revision		Revision as of 11:59, 14 September 2021
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 63:		Line 61:
	\|}		\|}

	=== 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 exception handling scheme.

			[[Category:Source Code Project]]

Niffiwan: /* General */ updates to match reality

2015-12-06T00:32:35Z

General: updates to match reality

← Older revision		Revision as of 00:32, 6 December 2015
Line 26:		Line 26:
	* 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 33:
	* 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 52:
	\|-		\|-
	\| 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 59:
	\| 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
	\|}		\|}

Niffiwan: /* C++ Exceptions */

2014-05-28T06:39:12Z

C++ Exceptions

← Older revision		Revision as of 06:39, 28 May 2014
Line 92:		Line 92:
	=== 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 ~~exceptional~~ handling scheme.		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.

Niffiwan: /* General */

2014-05-21T00:29:22Z

General

← Older revision		Revision as of 00:29, 21 May 2014
Line 34:		Line 34:
	\|-		\|-
	\| WarningEx( LOCATION, printf-formatted-message-needs-\n ); \|\| No \|\|		\| WarningEx( LOCATION, printf-formatted-message-needs-\n ); \|\| No \|\|
	* ~~I don't know what this~~ is ~~for~~		* 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-needs-\n ); \|\| Yes \|\|
Line 55:		Line 55:
	\|-		\|-
	\| VerifyEx( ??? ); \|\| Yes \|\|		\| VerifyEx( ??? ); \|\| Yes \|\|
	* ~~I don't know what this~~ is ~~for~~		* Same as Verify, except it will only trigger if the command line param "-extra_warn" is set
	\|-		\|-
	\| Int3(); \|\| No \|\|		\| Int3(); \|\| No \|\|
Line 62:		Line 62:
	* On other platforms I believe it acts like an Error		* On other platforms I believe it acts like an Error
	\|}		\|}


	=== LUA Scripting ===		=== LUA Scripting ===

Niffiwan: Created page with "== 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…"

2014-03-16T10:43:27Z

Created page with "== 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…"

New page

== 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.

{| border=1 cellpadding=5 style="background:#351515; border: 2px solid; border-collapse: collapse;"
|-
! 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 ||
* I don't know what this is for
|-
| 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 ||
* I don't know what this is for
|-
| 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.

{| border=1 cellpadding=5 style="background:#351515; border: 2px solid; border-collapse: collapse;"
|-
! 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.