wiki:PadawanPitfalls

Version 1 (modified by tim, 13 years ago) (diff)

Initial revision

Padawan Pitfalls

This page lists several problems that you are likely to encounter if you do not read this. Sounds weird? Read on, it gets even weirder!

Thread initialization and finalization

Thread initialization and finalization (from now on called inifin) is an important thing. Here are some things that you have to keep in mind:

init() must throw exceptions on error:

It is not enough to just detect that there is an error and log it. If there is anything that will violate the initialization assumptions in loop() you have to throw an exception, any exception will do! Re-throw an exception that you caught, create a new one. The important thing is that it has a meaningful error message (and is derived from Exception). If your init() method throws an exception the thread is never started! Thus you do not have to check in loop() for the resources claimed!

Free resources in init() on error:

If your initialization fails for any reason and you have to throw an exception, make sure that before throwing the exception you cleanup all the resources claimed and you unregister you thread from any facility that you registered it for (for example from the Fawkes Network Hub). The reason for this is that finalize() is not called in that situation (if the thread does not get started), and in the destructor it is not safe to destroy the resources because you don't know if or when init() failed.

finalize() may not throw exceptions:

Catch exceptions in finalize(), log the error and then go on with finalization. Since your thread is about to be stopped anyway you should finalize all you can, if there is an error log it and go on, do not stop the finalization after only half of it is done just because on step failed.

Free resources in finalize() claimed in init():

Any resources you claim in init() have to be freed in finalize(). For example close all BlackBoard interfaces that you opened, unregister from any facility you registered for etc.

Logging

Log as much as needed, and as little as possible:

Logging is a good thing in general, it helps to find bugs and to locate problems while running the software. But for two reasons it is a good things to use logging only sparsely: firstly logging is an expensive operation. Even if it is not that expensive, it's still extra work and consumes resources (IO is in general not that cheap because it is rather slow compared to everything else your plugin can do). Secondly if there are too many trees you don't see the forrest. This means that if you log too much the important stuff goes unseen. Thus report errors, and sparse special events that are good to now and happen rarely (like loading a plugin), log as much as you like during the development phase, but at a tournament make your application to shut the f* up.