Programming Reference:Error Handling - Revision history

Mellinger: /* Strategies */

2011-08-12T14:19:53Z

Strategies

← Older revision		Revision as of 14:19, 12 August 2011
Line 81:		Line 81:

	Programming errors are not supposed to occur at all in a tested version of an application. Therefore, instead of trying to 'handle' them, it is important to make them show up as close to their point of origin in the code as possible, by frequently and explicitly checking whether		Programming errors are not supposed to occur at all in a tested version of an application. Therefore, instead of trying to 'handle' them, it is important to make them show up as close to their point of origin in the code as possible, by frequently and explicitly checking whether
	implicit assumptions actually hold, and aborting execution with an error message if this is not the case.		implicit assumptions actually hold, and aborting execution with an error message if this is not the case.

			Typically, such checks use an "assertion" facility provided by the programming language. BCI2000 provides its own <tt>bciassert</tt> macro in <tt>BCIAssert.h</tt> to make sure that failed assertions result in messages that are displayed by the BCI2000 operator module. Unlike the standard assert macro, BCI2000 assertions do not evaluate to empty in release builds.

	Aside from that, writing code as explicit, general, and simple as possible greatly reduces the possibility of making logic errors in the first place.		Aside from that, writing code as explicit, general, and simple as possible greatly reduces the possibility of making logic errors in the first place.

Mellinger: /* Checking Parameters */

2011-08-12T14:14:16Z

Checking Parameters

← Older revision		Revision as of 14:14, 12 August 2011
Line 128:		Line 128:
	For the actual implementation, its declaration is as follows:		For the actual implementation, its declaration is as follows:

	void GenericFilter::Preflight ( const SignalProperties& ~~inSignalProperties~~,		void GenericFilter::Preflight ( const SignalProperties& Input,
	SignalProperties& ~~outSignalProperties~~ ) const;		SignalProperties& Output ) const;

	For a filter class derived from <tt>GenericFilter</tt>, this function is supposed to perform		For a filter class derived from <tt>GenericFilter</tt>, this function is supposed to perform
	parameter checking as described in the "Strategies" section. Instead of returning an error value, it writes possible error messages into <tt>bcierr</tt>. Furthermore, it communicates dimensions of its output signal which it guarantees not to exceed, and it does so by adjusting the properties of the second SignalProperties object in its argument list, e.g.		parameter checking as described in the "Strategies" section. Instead of returning an error value, it writes possible error messages into <tt>bcierr</tt>. Furthermore, it communicates dimensions of its output signal which it guarantees not to exceed, and it does so by adjusting the properties of the second SignalProperties object in its argument list, e.g.

	~~outSignalProperties~~ = SignalProperties( ~~inSignalProperties~~.Channels(), 1 );		Output = SignalProperties( Input.Channels(), 1 );

	or		or

	~~outSignalProperties~~ = SignalProperties( 0, 0 );		Output = SignalProperties( 0, 0 );

	if it declares not to use its output signal.		if it declares not to use its output signal.

	The <tt>const</tt> declaration for its <tt>this</tt> pointer prohibits initialization functionality from <tt>GenericFilter::Initialize()</tt> entering into <tt>Preflight()</tt>~~; this~~ is unwanted because it would corrupt the idea of performing a ''complete'' parameter check before actually ''altering'' the state of a filter object.		The <tt>const</tt> declaration for its <tt>this</tt> pointer prohibits initialization functionality from <tt>GenericFilter::Initialize()</tt> entering into <tt>Preflight()</tt>. Such behavior is unwanted because it would corrupt the idea of performing a ''complete'' parameter check before actually ''altering'' the state of a filter object.

	A necessary condition for a correct implementation of the <tt>Preflight()</tt> function is that any parameter, as well as any state that will be accessed during the processing phase, be accessed		A necessary condition for a correct implementation of the <tt>Preflight()</tt> function is that any parameter, as well as any state that will be accessed during the processing phase, be accessed

Mellinger: /* Accessing Environment Objects */

2011-08-12T14:11:38Z

Accessing Environment Objects

← Older revision		Revision as of 14:11, 12 August 2011
Line 211:		Line 211:
	If TransmitCh is greater than SourceCh, a message will be sent to <tt>bcierr</tt> and displayed to the user, stating:		If TransmitCh is greater than SourceCh, a message will be sent to <tt>bcierr</tt> and displayed to the user, stating:

	<tt>~~Condition not fulfilled~~:		<tt>A necessary condition is violated. Please make sure that the following is true:
	Parameter( "TransmitCh" ) <= Parameter( "SourceCh" )</tt>		Parameter( "TransmitCh" ) <= Parameter( "SourceCh" )</tt>

Mellinger: /* Reporting Errors */

2011-08-12T14:09:07Z

Reporting Errors

← Older revision		Revision as of 14:09, 12 August 2011
Line 119:		Line 119:
	if( ernie.find( bert ) != ernie.end() )		if( ernie.find( bert ) != ernie.end() )
	throw bciexception( "Ernie just ate Bert. I don't know how to tell the story." );		throw bciexception( "Ernie just ate Bert. I don't know how to tell the story." );
	tellMyStory( bert~~.begin(), ernie.end()~~ );		tellMyStory( ernie, bert );
	...		...

Mellinger: /* Reporting Errors */

2011-08-12T14:07:51Z

Reporting Errors

← Older revision		Revision as of 14:07, 12 August 2011
Line 115:		Line 115:
	Furthermore, for handling runtime errors from which it is difficult to recover, code may throw an exception that will abort execution and eventually lead to an error message being sent to the operator module (for framework related details see the section entitled "Implementation on the Framework Side"):		Furthermore, for handling runtime errors from which it is difficult to recover, code may throw an exception that will abort execution and eventually lead to an error message being sent to the operator module (for framework related details see the section entitled "Implementation on the Framework Side"):

			#include "BCIException.h"
	...		...
	if( ernie.find( bert ) != ernie.end() )		if( ernie.find( bert ) != ernie.end() )
	throw "Ernie just ate Bert. I don't know how to tell the story.";		throw bciexception( "Ernie just ate Bert. I don't know how to tell the story." );
	tellMyStory( bert.begin(), ernie.end() );		tellMyStory( bert.begin(), ernie.end() );
	...		...

Mellinger: /* Accessing Environment Objects */

2011-04-28T13:24:32Z

Accessing Environment Objects

← Older revision		Revision as of 13:24, 28 April 2011
Line 175:		Line 175:
	*<tt>Parameter(Name)[(Index 1[, Index 2])</tt>		*<tt>Parameter(Name)[(Index 1[, Index 2])</tt>

	This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use.(If the compiler complains about ambiguities, use explicit typecasts ~~as in the second example~~.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.		This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.
	~~(If the compiler complains about ambiguities, use explicit typecasts as in the second example.)~~

	Examples:		Examples:

Mellinger: /* Implementation on the Framework Side */

2010-06-29T13:37:21Z

Implementation on the Framework Side

← Older revision		Revision as of 13:37, 29 June 2010
Line 218:		Line 218:
	The behaviour of the operator module in response to an error message that arrives from one of the modules depends on its context, i.e., on the execution phase the system is in. That way, no additional programming interface elements visible to a filter/module programmer are needed to implement an error handling scheme as described in the "Handling Errors"section.		The behaviour of the operator module in response to an error message that arrives from one of the modules depends on its context, i.e., on the execution phase the system is in. That way, no additional programming interface elements visible to a filter/module programmer are needed to implement an error handling scheme as described in the "Handling Errors"section.

	During the '''preflight phase,''' errors are ~~{Parameter Setup~~ Errors}. A module's framework code behind <tt>bcierr</tt> just collects error messages; on return from the preflight function, it		During the '''preflight phase,''' errors are ''Configuration Errors''. A module's framework code behind <tt>bcierr</tt> just collects error messages; on return from the preflight function, it
	sends those messages to the operator module which then, from the contents of the message (i.e., whether it was empty or not), determines whether the preflight was successful; on not receiving any message after some timeout it assumes a broken connection or a crashed module.		sends those messages to the operator module which then, from the contents of the message (i.e., whether it was empty or not), determines whether the preflight was successful; on not receiving any message after some timeout it assumes a broken connection or a crashed module.

	(For now, a simple timeout scheme with a fixed timeout interval of 5s seems appropriate. In the future, one might consider a module requesting additional timeout periods if it expects lengthy calculations.)		(For now, a simple timeout scheme with a fixed timeout interval of 5s seems appropriate. In the future, one might consider a module requesting additional timeout periods if it expects lengthy calculations.)

	During all '''other phases,''' the code behind <tt>bcierr</tt> immediately (i.e., on flushing the <tt>std::ostream</tt>) sends its message buffer to a log file as well as to the operator module, indicating a {Runtime Error} to the operator module which will, in turn, halt the system,shut down the other modules, and display the message to the user.		During all '''other phases,''' the code behind <tt>bcierr</tt> immediately (i.e., on flushing the <tt>std::ostream</tt>) sends its message buffer to a log file as well as to the operator module, indicating a ''Runtime Error'' to the operator module which will, in turn, halt the system,shut down the other modules, and display the message to the user.

	In addition, the top level exception handling code of each module contains similar functionality,		In addition, the top level exception handling code of each module contains similar functionality,
	sending an exception's associated description string into a log file and to the operator module, if possible, then quitting the module in which the exception occurred. This not only ensures		sending an exception's associated description string into a log file and to the operator module, if possible, then quitting the module in which the exception occurred. This not only ensures
	a proper general handling of exceptions within the framework but also allows a programmer to handle {Runtime Errors} by raising her own exceptions, eliminating the need to take care of the error		a proper general handling of exceptions within the framework but also allows a programmer to handle ''Runtime Errors'' by raising her own exceptions, eliminating the need to take care of the error
	condition in the code following the detection of an error.		condition in the code following the detection of an error.
	----		----

	==See also==		==See also==
	[[Programming Reference:Errors and Warnings]], [[Programming Reference:Environment Class]], [[Programming Reference:Debug Output]]		[[Programming Reference:Errors and Warnings]], [[Programming Reference:Environment Class]], [[Programming Reference:Debug Output]]

	[[Category:Framework API]][[Category:Development]]		[[Category:Framework API]][[Category:Development]]

Mellinger: /* Accessing Environment Objects */

2008-03-11T08:57:57Z

Accessing Environment Objects

← Older revision		Revision as of 08:57, 11 March 2008
Line 197:		Line 197:
	State( "OfAffairs" ) = nextStateOfAffairs;		State( "OfAffairs" ) = nextStateOfAffairs;

	*<tt>OptionalState(Default Value~~, Name~~)</tt>		*<tt>OptionalState(Name[, Default Value])</tt>

	Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.		Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.

Mellinger at 17:23, 8 November 2007

2007-11-08T17:23:00Z

← Older revision		Revision as of 17:23, 8 November 2007
Line 231:		Line 231:
	----		----
	==See also==		==See also==
	[[Programming Reference:Errors and Warnings]]\|[[Programming Reference:Environment Class]]\|[[Programming Reference:Debug Output]]		[[Programming Reference:Errors and Warnings]], [[Programming Reference:Environment Class]], [[Programming Reference:Debug Output]]

			[[Category:Framework API]][[Category:Development]]

Mellinger at 10:17, 7 November 2007

2007-11-07T10:17:26Z

← Older revision		Revision as of 10:17, 7 November 2007
Line 229:		Line 229:
	a proper general handling of exceptions within the framework but also allows a programmer to handle {Runtime Errors} by raising her own exceptions, eliminating the need to take care of the error		a proper general handling of exceptions within the framework but also allows a programmer to handle {Runtime Errors} by raising her own exceptions, eliminating the need to take care of the error
	condition in the code following the detection of an error.		condition in the code following the detection of an error.
			----
			==See also==
			[[Programming Reference:Errors and Warnings]]\|[[Programming Reference:Environment Class]]\|[[Programming Reference:Debug Output]]