Programming Reference:Errors and Warnings

From BCI2000 Wiki
Jump to: navigation, search

Output Streams

There are two output channels available to any code inside a BCI2000 module. Technically, these channels are global objects derived from the STL's std::ostream class. As such, they work much like the global std::cout and std::cerr output streams available inside a C++ command line program, except that their output will be sent to the operator module's log window rather than a terminal window.

Writing into Error and Warning Streams

The names of these output streams are bciout and bcierr, declared in shared/BCIError.h, and while writing output to bciout has no side effects, writing to bcierr has side effects that depend on the system's phase of operation: In preflight phase, the side effect will be a preflight failure, and the system will not start unless reconfigured with correct parameters; otherwise, the side effect will be system termination after error display.

Note that writing into bcierr or bciout has no effect before the stream's output buffer is flushed by inserting endl or flush:

bcierr << "Display this immediately!" << endl;

Convenience Macros

For the Preflight function, there is also a macro PreflightCondition available that is intended to make checking for conditions more convenient:

PreflightCondition( Parameter( "MyFirstParam" ) >= 3 );

will result in a message

"A necessary condition is violated: Parameter( "MyFirstParam" ) >= 3"

in the operator window if MyFirstParam's value is below 3.

Throwing Exceptions

Finally, in case of a non-recoverable error, you may also throw an exception of type BCIException in order to report an error in the operator window, and to terminate the BCI2000 system after the error has been displayed. For convenience, there is a macro bciexception that allows you to use stream inserters when specifying the error message:

#include "BCIException.h"
...
throw bciexception( "Illegal value of n: " << n );

Assertions

In addition to bciexception, there is a macro bciassert that takes a condition as an argument, and throws an exception of type BCIException when that condition evaluates to false. The exception's message contains "Assertion failed", and reports the location of the failure along with the condition itself. To use this macro, include the "BCIAssert.h" header file:

#include "BCIAssert.h"
...
bciassert( inIdx < mContainer.size() );

Do only use assertions when a failure indicates a programming error, not a user configuration error. Especially, don't use bciassert in the GenericFilter::Preflight() function because it will terminate BCI2000, and not allow the user to modify parameter settings. To test for conditions in the Preflight() function, use the PreflightCondition macro described above.

Unlike the standard assert macro, bciassert will always be active, not only in debug builds.

See also

Programming Reference:Error Handling for a more detailed discussion of error reporting facilities.