Exiting due to error: FLAbort vs FLExit

Coding Rules

The only manner in which fluidity should exit due to error is using the FLAbort , FLExit or assert macros. In this context exiting due to error refers to any circumstances in which execution ceases except due to the simulation finishing of its own accord or being instructed to finish by an external signal. Calls to stop or exit() are prohibited.

Tutorial

FLAbort

The FLAbort macro will cause fluidity to halt and all relevant clean-up (especially with respect to MPI) to occur. A suitable message will be printed. The FLAbort macro should be used when the exit is caused by developer or coding error (i.e. not due to user input error). The syntax of FLAbort is:

FLAbort(<error message>)

<error message> must be a string valued expression and is usually a literal string enclosed in quotation marks. In addition to the error message the FLAbort macro also prints a backtrace, where available, to indicate the location and code path causing the error. Note that since FLAbort is a preprocessor macro, its invocation is case sensitive and it must be spelled using the casing presented here.

FLExit

The FLExit macro will cause fluidity to halt and all relevant clean-up (especially with respect to MPI) to occur. A suitable message will be printed. The FLExit macro should be used when the exit is caused by user input error (i.e. not by coding or developer error). The syntax of FLExit is:

FLExit(<error message>)

<error message> must be a string valued expression and is usually a literal string enclosed in quotation marks. The message should be concise, but informative and if possible, give a solution to the problem.

Note that since FLExit is a preprocessor macro, its invocation is case sensitive and it must be spelled using the casing presented here.

assert

assert will check that the logical expression provided to it and will exit if it returns .false.. A message indicating the assertion that has failed will be printed. An assert will only be run when debugging is enabled.

assert should be used when the exit is caused by coding or developer error (i.e. not user input error). The syntax of assert is:

assert(<logical expression>)

<logical expression> must be an expression that returns a logical.

Hints and Tips

FLAbort and FLExit shouldn't be used to write a lot of text to the output. A useful thing is to use a number of "ewrite" statements. In particular ewrite(-1,*) will write to screen regardless of what the verbosity level is set at.