[Scummvm-devel] ATTN Porters: New "logging" API in OSystem
Johannes Schickel
lordhoto at scummvm.org
Thu Nov 18 20:50:05 CET 2010
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
More information about the Scummvm-devel
mailing list