Chapter 2.4 - Exceptions / Error handling (by Johannes Nicolai)

If you encounter an error, that you cannot handle properly in your component, the only way to report it is to throw an exception. See the header files of your components to see what exceptions are allowed to be thrown by the different methods. In most cases, this will be an Exceptions::StrategyException (class Exceptions::StrategyException [exceptions/strategyexception.h]). An example:

	double BFClientSpecificRepository::getTimePassed() const throw(StrategyException) {
		timespec dummy;
		if (clock_gettime(CLOCK_REALTIME,&dummy))
			throw StrategyException(string("Getting the passed time for a new shoot \ 
				failed in Brotfrucht strategy: ")+strerror(errno));
			return double(1000000000.0)*(dummy.tv_sec-_timerstart.tv_sec)+ \ 
				dummy.tv_nsec-_timerstart.tv_nsec;
	}

How to set and configure the logger

One more useful tool to debug your strategy is the logger. All characteristics of the section's logger are specified in the global configuration file, take this code as example:

    [UnixClientCommunicator]
    logPriority="7"
    logDriverName="UnixFileLogDriver"
    logDriverParameters="file:/tmp/foo.log"

As you can see, every section that may use a logger, have to specify values (do not forget the quotes) for the keys:

  1. logPriority: Threshold value, messages with lower priorities will not be passed to the log driver at all (useful for debugging purposes).
  2. logDriverName: Type of the logging driver, that should be used, currently we support:
    • UnixFileLogDriver: writes log messages in a file that does not exist before starting the robot (multiple sections can write in same file).
    • SyslogLogDriver: writes log messages to the syslog daemon (multiple sections can write to same daemon).
    • RTBLogDriver: writes log messages into the message window of the RealTimeBattle Server, please note that this may slow down speed significantly.
    • NullLogDriver: does not write the messages at all, useful for performance reasons.
    It is very easy to plugin further log drivers to the framework, see the logging API for details.
  3. logDriverParameters: Contains a string that is specific for the used log driver:
    • UnixfileLogDriver: see above example of the syntax of logDriverParameters, more is not supported currently.
    • NullLogDriver: the value of logDriverParameters is ignored.
    • RTBLogDriver: logCommand:Print means to print messages via the Print command to the RealTimeBattle server, logCommand:Debug means to use Debug for it and logCommand:Both means to use both ways.
    • SyslogLogDriver: First of all, read the manual page of syslog(3) in order to get used with the terminology. The driver will only log to the facility LOG_USER, all other parameters you are able to specify: ident (programname that will appear in syslog), option (options, e.g. LOG_PID, if the PID should be displayed in syslog) and priority (he different levels (from LOG_DEBUG to LOG_EMERG), that has nothing to do with the framework priorities).
    Whereas, like in C-programs the C- constants LOG_* can be used, in this cased also ORED together via "|". Thus, a typical value for logDriverParameters would be ident: RTB-Team, option: LOG_CONS|LOG_PID, priority: LOG_INFO.

At last, we want to tell you how to use the obtained logger object:

    _logger->logMessage(27,"All subsystems functioning") will write this message \
    	with priority 27 to the underlying log driver.

Whether 27 is a high priority or not you can decide by your own because every section logger has its own threshold value. Usually, priorities are between 1 (not important at all, debugging messages) up to 100 (fatal error).

Things not to forget

Like every project, rtb team framework has several rules like coding standards, naming conventions, exception conventions, ... All information about writing proper code is contained in the sourceforge documentation manager. Here you will also find further details about the internal design of the framework, minutes of the meetings of the different groups and logs of irc sessions between the framework and strategy developers. At last we have the mailing list and a strategy forum to discuss all things related with rtb. Also take a look about our web site and the official RealTimeBattle information (here you can find the documentation about the different messages sent by the RealTimeBattle Server and the commands a robot can send to it.