Changes between Initial Version and Version 1 of code/doc/Exception

Timestamp:

Sep 4, 2008, 10:26:02 AM (16 years ago)

Author:

rgrieder

Comment:

—

code/doc/Exception

@@ +1 @@
+= Exceptions, Assertions and COUT =
+Whenever something unwanted happens, the programmer needs to react in a certain way.[[br]]
+We support three different ways to handle such situations:
+ * Display a message in the console, shell and log
+ * Throw an exception that can be caught
+ * Abort the program with a message
+[[br]]
+
+== COUT(#), displays messages ==
+Whenever you want to show the user or the programmer a message, use COUT(#) where # is a number denoting the output level:
+|| # || Meaning ||
+|| || ||
+|| 0 || Gets always displayed and is mean for messages like "loading level 'foo.bar'" ||
+|| 1 || Errors. Something seriously bad has happened. Mostly in combination with assert() or an exception. ||
+|| 2 || Warnings. The issue is not too bad, but everyone should see that something bad has happened. ||
+|| 3 || Slight debug information. Not intended to be displayed to the end-user, but surely every beta tester. ||
+|| 4 || Debug information. Can be quite a lot of text. ||
+|| 5 || Verbose debug information. That would be overkill in the shell or console. View the log! ||
+|| 6 || Extreme debug information. You better use grep or another regex tool to read a log file for level 6. ||
+[[br]]
+
+You can configure the displayed levels for all output devices: Shell, console and log. Default value is around 3. There is also a possibility to define a hard debug level, so that the COUT(#) calls don't even get compiled above a that level. [[br]][[br]]
+'''Note: A simple message with level 1 doesn't trigger an exception or anything yet!'''
+
+== Exceptions ==
+This kind of error handling method is used when the programmer has to handle situations that could go wrong, but shouldn't. This does not count obvious C++ programming mistakes! (see Assertions below) [[br]]
+When an exception gets thrown its message, containing file, line number, function name, exception type and programmer message, is displayed via COUT(4). That means you usually don't see them anywhere because it is better left to the programmer to display the error at the right position. But you can still open the log and search for it unless the log debug level is below 4. [[br]][[br]]
+
+To throw an exception you best use the 'ThrowException(type, message)' macro that automatically adds line number, function and file name. 'Type' is a user defined derived class of orxonox::Exception so that different exceptions can be caught with different 'catch' clauses. [[br]]
+Currently available types are: [[br]]
+|| Name || Description ||
+|| || ||
+|| General || Anything. Avoid using it and rather define a new one. ||
+|| FileNotFound || Obviously a file was not found ||
+|| Argument || A function argument in a parser was wrong. ||
+|| PluginsNotFound || No Ogre plugins were found but are required ||
+|| InitialisationFailed || When starting the game engine, something went terribly wrong. ||
+|| NotImplemented || The feature requested has not yet been implemented ||
+|| GameState || Something went wrong with a GameState class ||
+[[br]]
+
+== Assertions ==
+Last but not least: Assertions. This is very handy programmer's tool. It helps a lot tracking bugs and sets up a newly created class much quicker. [[br]]
+When should you use it? Basically, an assertion is used when the programmers assumes that a certain condition is true and that otherwise the program would fail somewhere. [[br]][[br]]
+An example: In a function, you receive a pointer and do something like ptr->aMemberFunction() while assuming that ptr != 0 because otherwise, you'll probably get a segmentation fault.
+
+{{{
+void fooBar(myClass* ptr)
+{
+    ...
+    ptr->aMemberFunction();
+}
+}}}
+
+You can now insert a call to the 'asser()' macro so that whenever ptr == 0 the program aborts. Now this doesn't sound very help, but it is: First of all, the abort message tells you exactly where the error has happened (file, line, function). Secondly, the program would have aborted anyway because of the null pointer. [[br]][[br]]
+The more asserts you insert, the easier bug tracking will be. You might even spot them before they could ever be triggered. [[br]][[br]]
+'''Important: Asserts are only useful when the mistake is in the program. Throwing asserts for bad input doesn't help anyone, use exceptions then!''' [[br]]
+
+Usage: 'assert(condition you assume);' or when you want to tell more use 'OrxAssert(condition, message)'. The message gets then displayed via COUT(1) before the assert() macro is called. [[br]]
+The example above would then read:
+
+{{{
+void fooBar(myClass* ptr)
+{
+    ...
+    OrxAssert(ptr != 0, "You screwed the wrong pointer!");
+    ptr->aMemberFunction();
+}
+}}}