Rules for return status of algorithms running in production applications

• Algorithms should always return StatusCode::SUCCESS from execute()
  • StatusCode::FAILURE stops the processing, so must be limited to irrecoverable errors affecting all following events. One example is if an algorithm does not find its input data container since this should always be there - its absence would point to a configuration problem with the application, or a bug in the algorithm that should have created the input data.
  • Any failure of methods and tools called from execute must be trapped in the algorithm and not propagated to the application. For example:
    
    StatusCode myAlg::execute() {
      StatusCode sc = m_tool->doSomething();
      if ( sc.isFailure() ) { return Error("Some meaningful message", StatusCode::SUCCESS); }
      m_tool->doSomethingElse();
      return StatusCode::SUCCESS;
    }

• Sometimes an algorithm may detect a condition that makes it meaningless to continue processing the event. There are two distinct possibilities:

  1. Processing should stop only for the Sequence inside which the algorithm is executed. In this case one uses the filtering capability of GaudiSequencer:
     

         this->setFilterPassed( false );
         return Error( "xxxx error, skipping rest of sequence", StatusCode::SUCCESS );

  2. Processing should stop for all remaining TopAlgs and Sequences in the event. In this case one should fire the AbortEvent incident as well as stopping the current sequence:

         // Get pointer to IncidentSvc in initialize()
         m_incidentSvc = svc<IIncidentSvc>("IncidentSvc",true);

         // Fire the incident in execute()
         m_incidentSvc->fireIncident(Incident(name(),IncidentType::AbortEvent));
         this->setFilterPassed( false );
         return Error( "yyyy error, skipping the rest of the event", StatusCode::SUCCESS );

• Algorithms may return StatusCode::FAILURE during initialize() in cases where a configuration problem makes the processing of events meaningless

  • In this case, algorithms MUST print an Error() explaining the reason for the failure
     
• Do not to return StatusCode::FAILURE during finalize(), as this prevents the following algorithms from being finalized.
  • In case of a serious problem in finalize(), report with a Warning()
  or Error().
  
• A corollary of these rules it that you should NEVER call functions such as assert(), which cause the program to terminate without returning control to the application manager

Note

Most of the LHCb code uses the status code as an effective "boolean" value, which is perfectly fine. But one also could use the value of the code to discriminate between possible errors - for example:

if ( a == 0 ) { return StatusCode ( 100 ) ; }
else if ( 0 > a ) { return StatusCode ( 200 ) ; }

double b = pow( a , -1.0/3.0 ) ;
...
return StatusCode::SUCCESS;

The status code could be inspected: e.g.

StatusCode spendCPUtime ( ) ;
....
StatusSode sc = spendCPUtime() ;
if ( sc.isFailure() )  {
  // check with some predefined value
  if ( 100 == sc.getCode() ) {
    // I know how to recover this error!!!
    if(MsgLevel(MSG::DEBUG)) debug() << " I know how to recover!!!" << endmsg;
    .. Action here ..
  }
  else if ( 200 == sc.getCode() ) {
    if(MsgLevel(MSG::DEBUG)) debug() << " check matrix calculations!!! " << endmsg ;
    .. Action here ...
  }
  else {
    if(MsgLevel(MSG::DEBUG)) debug() << " some general/unspecified error " << endmsg ;
    .. Action here ...
  }
}

Note also that the functions Error(), Warning() etc. have an argument which takes the value of status code and print the numerical value of code if it is not 0 or 1, which is very helpful in debugging.

StatusCode sc = ;;;
if ( ... ) sc = 10 ;
else if ( ... ) sc = 12345 ;
else if ( ... ) sc = 432455 ;

if ( sc.isFailure() ) { return Error("problem here!", sc ) ; } // RETURN STATUS CODE VALUE
 

By convention, StatusCode must always be tested (if a function returns a status, there must be a reason, otherwise it may as well return void). If there is a good reason for not testing it, ignore it explicitly by adding .ignore() to the function returning the StatusCode, e.g. Warning("some warning").ignore(); You can check whether your code is testing all StatusCodes by enabling the StatusCode checking auditor: ApplicationMgr().StatusCodeCheck = True;