[Scummvm-devel] ATTN Porters: New "logging" API in OSystem

[Johannes Schickel]

Hi,

as some of you might have noticed recently Max proposed some new API, so 
that backends can easily handle where debug/warning/error messages are 
outputted to. If you did not follow that discussion I will shortly recap 
the new methods which were added now:

OSystem::fatalError:

The prototype of this function is "void fatalError()".

OSystem::fatalError was introduced to indicate to the backend that a 
fatal error occured and that ScummVM should be quit. Unlike 
OSystem::quit, which should also quit the application, fatalError is 
only called when a fatal error occured.

The default implementation just uses OSystem::quit. You all should make 
sure that at least OSystem::quit is implemented according to the 
specification in your backend. If you additional want some special 
handling for fatal errors make sure you implement fatalError too.

OSystem::logMessage:

The prototype of this function is "void logMessage(LogMessageType::Type 
type, const char *message)".

This newly introduced method is called whenever the client code wants to 
log some message. Currently it is used in debug*/warning and error.

You might also want to notice the enum in the namespace LogMessageType, 
which is used to indicate what type of log message is passed. There are 
currently three types of messages: kError, kWarning and kDebug. I think 
they are self explanatory, in case you have any questions when which is 
used feel free to ask.

How you handle the different log messages is up to you, but it is 
encouraged to do so in a non-buffered manner, i.e. directly store them 
somewhere.

The default implementation will output errors and warnings to stderr and 
debug information to stdout.

A small note from my side: It is probably not a good idea to the 
messages to the user via some GUI dialog or the like, since after all 
those messages are more meant to be a developer oriented output / for 
debugging.


Since nowadays the backend is responsible for outputting the log 
messages, it should be noted that debug/warning/error will not be able 
to output anything before g_system is initialized. Also if your backend 
has special logging facilities be aware that you should not call 
debug*/warning or error in your backend anymore before those are 
initialized.


I also have some special notes to the porters of the following backends: 
Android, Symbian and SamsungTV. In case you do not work on those ports 
you will find no useful information after this line. In case you do work 
on them please read on.

Android:

I implemented logMessage according to what was done before in 
debug/warning/error. I noticed that in case of error it seems some 
"__android_log_assert" function is called, which looks like it would 
quit ScummVM. This is not the intended behavior. Angus you have time 
please change the case for kError in android.cpp so it only logs the 
error message.

I also want to say that I didn't have any way to test compilation of 
your backend, so I can not assure that I did not break compilation, if I 
did I am sorry about that.

SamsungTV:

It seems SamsungTV does not implement ::exit correctly. At least in 
::error it was replaced with an endless loop. I would really like to see 
a proper ::exit implementation, after that the special case in ::error 
can be removed and also OSystem_SamsungTV::fatalError can be deleted. So 
please Aquadran if you find time take a look into this.

A possible solution would be to introduce some "exit" macro which is 
replaced by an endless loop.

I also want to say that I didn't have any way to test compilation of 
your backend, so I can not assure that I did not break compilation, if I 
did I am sorry about that.

Symbian:

It seems Symbian has it's own "FatalError" function, which is called in 
::error. This function should be integrated into OSystem::fatalError. 
Since the Symbian function also takes a string and also shows a GUI 
dialog to the user it is not trivial to do that. Please anotherguest, if 
you find any time adapt Symbian to the latest changes and also remove 
the Symbian::FatalError call in ::error.

// Johannes