Page History

Tasks that run for extended periods of time should All tasks in a thread pool must provide a notification mechanism to alert upper layers when mechanism for notifying the application if they terminate abnormally. Failure to do this does not so cannot cause any resource leaks because the threads in the pool are still recycled, however, but it makes failure diagnosis extremely difficult or impossible.

The best way to handle exceptions at a global the application level is to use an exception handler. The handler can perform diagnostic actions, clean - up and shutdown shut down the Java Virtual Machine (JVM) , or simply log the details of the failure. This guideline may be violated if the code for all runnable and callable tasks has been audited to ensure that no exceptional conditions are possible. Nonetheless, it is usually a good practice to install a task specific or global exception handler to initiate recovery.

Noncompliant Code Example (Abnormal Task Termination)

This noncompliant code example consists of the PoolService class PoolService that encapsulates a thread pool and a runnable Task class, . The Task. The run() method of the task can throw runtime exceptions, such as NullPointerException.

final class PoolService {
  private final ExecutorService pool = Executors.newFixedThreadPool(10);
		  
  public void doSomething() {	   
    pool.execute(new Task());
  }	
}

final class Task implements Runnable {
  @Override public void run() {
    // ...
    throw new NullPointerException();
    // ...	
  }
}

The task does not notify upper layers fails to notify the application when it terminates unexpectedly as a result of the runtime exception. Moreover, it does not use any recovery mechanismlacks a recovery mechanism. Consequently, if Task were to throw a NullPointerException, the exception would be ignored.

Compliant Solution (

...

ThreadPoolExecutor Hooks)

Task-specific recovery or cleanup actions can be performed by overriding the afterExecute() hook of the java.util.concurrent.ThreadPoolExecutor class. This hook is called either when a task concludes successfully by executing all statements in its run() method or when the task halts because of an exception. Some implementations may fail to catch java.lang.Error (see Bug ID 6450211 for more information [SDN 2008]). When using this approach, substitute the executor service with a custom ThreadPoolExecutor that overrides the afterExecute() hook:This compliant solution refactors the task so that it catches Throwable and forwards it to a custom exception reporter (see EXC01-J. Use a class dedicated to reporting exceptions for details on class MyExceptionReporter).

// ...

final class Task implements RunnablePoolService {
  @Override// publicThe voidvalues run() {
    try {
      // ...
      throw new NullPointerException();
    have been hard-coded for brevity
  ExecutorService pool = new CustomThreadPoolExecutor(
      10, 10, 10, TimeUnit.SECONDS, new ArrayBlockingQueue<Runnable>(10));
  // ...
}

class CustomThreadPoolExecutor   } catch(Throwable t)extends ThreadPoolExecutor {
      // Execute... any recovery codeConstructor ...
      MyExceptionReporter.report(t);	 public CustomThreadPoolExecutor(
    } finally {
int corePoolSize, int maximumPoolSize,   // Perform clean-up actionslong keepAliveTime, 
    }   	
  }
}

A finally block can be used to perform clean-up actions. If the task cannot be refactored, it may be wrapped within a Runnable or Callable that catches Throwable, and submitted to the thread pool.

Task specific recovery or clean-up actions can also be performed by overriding the class {{java.util.concurrent.ThreadPoolExecutor}}'s {{afterExecute()}} hook. This hook is called when a task completes successfully by executing all statements in its {{run()}} method, or halts because of an exception (A {{java.lang.Error}} might not be captured on specific implementations, see [Bug ID 6450211|http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6450211] \[[SDN 08|AA. Java References#SDN 08]\]). When using this approach, substitute the executor service with a custom {{ThreadPoolExecutor}} that overrides the {{afterExecute()}} hook as shown below:

class CustomThreadPoolExecutor extends ThreadPoolExecutor {
  // ... Constructor ...

  @Override
  public void afterExecute(Runnable r, Throwable t) {
    super.afterExecute(r, t);TimeUnit unit, BlockingQueue<Runnable> workQueue) { 
    super(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue);
  }


  @Override
  public void afterExecute(Runnable r, Throwable t) {
    super.afterExecute(r, t);
    if (t != null) {
      // Exception occurred, forward to handler
    }
    // ... Perform task-specific recovery and clean-upcleanup actions
  }

  @Override
  public void terminated() {
     super.terminated();
     // ... Perform final clean-up actions
  }
}

Similarly, the The terminated() hook is called after all the tasks have finished executing , and the Executor has terminated cleanly. This hook can be overridden to release resources acquired by the thread pool over its lifetime, much like a finally block.

Compliant Solution (Uncaught

...

Exception Handler)

This compliant solution sets an uncaught exception handler on behalf of the thread pool. During its construction, an argument of type ThreadFactory A ThreadFactory argument is passed to the thread pool during construction. The factory is responsible for creating new threads and setting the uncaught exception handler on their behalf. The Task class Task remains the same as the is unchanged from the noncompliant code example.

final class PoolService {
  private static final ThreadFactory factory =
  new
    new ExceptionThreadFactory(new MyExceptionHandler());
  private static final ExecutorService pool =
      Executors.newFixedThreadPool(10, factory);

  public void doSomething() {	   
    pool.execute(new Task()); // Task is a runnable class	      	    	      
  }
 
  public static class ExceptionThreadFactory implements ThreadFactory  {			
    private static final ThreadFactory defaultFactory =
        Executors.defaultThreadFactory();
    private final Thread.UncaughtExceptionHandler handler;

    public ExceptionThreadFactory(
        Thread.UncaughtExceptionHandler handler)
    {
      this.handler = handler;
    }

    @Override public Thread newThread(Runnable run) {
      Thread thread = defaultFactory.newThread(run);
      thread.setUncaughtExceptionHandler(handler);
      return thread;
    }
  }
	  
  public static class MyExceptionHandler extends ExceptionReporter
 
     implements Thread.UncaughtExceptionHandler {

    private final Logger logger = Logger.getLogger("com.organization.Log");
    // ... 

    @Override public void uncaughtException(Thread thread, Throwable t) {
      // Recovery or logging code
    }
  logger.log(Level.SEVERE, "Thread exited with exception: " + thread.getName(), t);			      
    }
  }	  
}

Note that the uncaught exception handler is not called if the method {{ExecutorService.submit()}} is invoked. This is because the thrown exception is considered to be part of the return status and is consequently, re-thrown by {{Future.get()}}, wrapped in an {{ExecutionException}} \[[Goetz 06|AA. Java References#Goetz 06]\]. 

Risk Assessment

}
}

The ExecutorService.submit() method can be used (in place of the execute() method) to submit a task to a thread pool and obtain a Future object. When the task is submitted via ExecutorService.submit(), thrown exceptions never reach the uncaught exception handler because the thrown exception is considered to be part of the return status and is consequently wrapped in an ExecutionException and rethrown by Future.get() [Goetz 2006a].

Compliant Solution (Future<V> and submit())

This compliant solution invokes the ExecutorService.submit() method to submit the task so that a Future object can be obtained. It uses the Future object to let the task rethrow the exception so that it can be handled locally.

final class PoolService {
  private final ExecutorService pool = Executors.newFixedThreadPool(10);

  public void doSomething() {
    Future<?> future = pool.submit(new Task());

    // ...

    try {
      future.get();
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } catch (ExecutionException e) {
      Throwable exception = e.getCause();
      // Forward to exception reporter
    }
  }
}

Furthermore, any exception that prevents doSomething() from obtaining the Future value can be handled as required.

Exceptions

TPS03-J-EX0: This rule may be violated only when the code for all runnable and callable tasks has been audited to ensure that exceptional conditions are impossible. Nonetheless, it remains good practice to install a task-specific or global exception handler to initiate recovery or log any exceptional conditions.

Risk Assessment

Failure to provide a mechanism for reporting Failing to provide a mechanism to report that tasks in a thread pool failed as a result of an exceptional condition , can make it harder difficult or impossible to find the source of the issuediagnose the problem.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

\[[API 06|AA. Java References#API 06]\] interfaces {{ExecutorService}}, {{ThreadFactory}} and class {{Thread}}
\[[Goetz 06|AA. Java References#Goetz 06]\] Chapter 7.3: Handling abnormal thread termination

To-Do List

 
||Completed||Priority||Locked||CreatedDate||CompletedDate||Assignee||Name|| 

Related Guidelines

Bibliography

...

Image Added Image Added Image AddedCON12-J. Avoid deadlock by requesting and releasing locks in the same order      11. Concurrency (CON)      VOID CON14-J. Ensure atomicity of 64-bit operations