Declaration of throw for generic exception

A function throws a generic exception, which might have many subtypes

Since R2022a

Description

This defect occurs when a function throws a generic exception. Polyspace^® checks the throw statements, dynamic exception specifications, or the documentation of a function and raises this defect if any of these conditions is true:

The function contains throw statements that raise generic exceptions.
The dynamic exception specification contains generic exceptions.
The function is documented with a @throw comment that contains generic exceptions.

Polyspace considers exceptions of the class std::exception as generic.These are base exception classes that have many derived exception classes.

Risk

Raising generic exceptions hinders proper error handling and error recovery. For instance:

void foo(void) throw(std::exception){
	//...
}

void caller(void){
	try{
		//...
		foo();
	}catch(std::exception& e){
		// Need to figure out what the error is.
	}
}

When handling the exceptions raised by foo(), determining what errors might happen in foo() is handled by caller(). Because the exception specification of foo() is broad, the emergence of new or unexpected exceptions might not be detected. Handling and recovering from errors in foo() becomes more complicated for caller().

Fix

To resolve this defect, use specific exceptions when documenting the exception in a function. Caller functions are then able to address specific exceptions by using specific error-handling code. Unexpected exceptions are easily detected.

Examples

expand all

Avoid Generic Exception Specification

#include<exception>
#include<stdexcept>
#include<iostream>

void foo(void) throw(std::exception){  
	//...
}
// @throw std::exception
void bar() {  //Noncompliant
	//...
	throw std::exception(); 
}

void foo1(){
	//...
	throw std::exception(); 
}
int main(void){
	try{
		//...
		foo();
	}catch(std::exception& e){
		// Need to figure out what the error is.
		
	}
	try{
		//...
		bar();
	}catch(std::exception& e){
		// Need to figure out what the error is.
		
	}
	try{
		//...
		foo1();
	}catch(std::exception& e){
		// Need to figure out what the error is.
		
	}
}

In this example, Polyspace flags the generic throw specifications. For instance:

Polyspace flags the dynamic exception specification of foo() because it uses std::exception.
Polyspace flags the function bar() because it is documented to raise the generic exception std::exception. Polyspace also flags the generic throw statement in this function.
Polyspace flags the generic throw statement in foo1().

Because these functions raise generic exceptions, identifying the exceptions is handled by the caller function main(). Because the caller does not know which specific exception are expected, it might fail to detect unexpected exceptions.

Correction — Use Specific Exceptions

To fix this issue, document specific exceptions that might arise from a function. This specific documentation enables the caller function to address specific exceptions. Unexpected exceptions become unhandled exceptions and are easily detected.

#include<exception>
#include<stdexcept>
#include<iostream>

void foo(void) throw(std::overflow_error){
	//...
}
// @throw std::invalid_argument
void bar() {                    
	//...
}

void foo1(){
	//...
	throw std::range_error("MSG"); 
}
int main(void){
	try{
		//...
		foo();
	}catch(std::overflow_error& e){
		// Expecting an overflow.
		
	}
	try{
		//...
		bar();
	}catch(std::invalid_argument& e){
		// Expecting an invalid argument.
		
	}
	try{
		//...
		foo1();
	}catch(std::range_error& e){
		// Expecting a range error.
		
	}
}

Result Information

Group: Good practice

Language: C++

Default: Off

Command-Line Syntax: THROW_FOR_GENERIC_EXCEPTION

Impact: Low

Version History

Introduced in R2022a