Cleaned up CA exceptions. Integrated free-standing handle class.

installer/src/installer-lib/process.h

 /**
  * \file process.h
  */
 
 #ifndef PROCESS_H
 #define PROCESS_H
 
+#include "handle.h"
+
 #include <vector>
 #include <set>
 #include <algorithm>
 #include <memory>
 
 #include <Windows.h>
 #include <TlHelp32.h>
 
-//-------------------------------------------------------
-// Windows_Handle
-//-------------------------------------------------------
-/**
- * A handle to some Windows platform resource. 
- *
- * Note, this is not the same as a Windows Installer handle (MSIHANDLE).
- * The two handles have different underlying types and use different functions to close.
- */
-class Windows_Handle
-{
-public:
-  /**
-   * Ordinary constructor.
-   *
-   * Validates argument against INVALID_HANDLE_VALUE. No other checks performed.
-   */
-  Windows_Handle( HANDLE h ) ;
-
-  /**
-   * Destructor
-   */
-  ~Windows_Handle() ;
-
-  /**
-   * Conversion operator to underlying HANDLE.
-   */
-  operator HANDLE() const { return handle ; } ;  
-
-  /**
-   * Raw handle assignment.
-   *
-   * This is equivalent to destroying the old object and constructing a new one in its place.
-   * In C++11 this would be handled by the move constructor on an rvalue reference.
-   */
-  void operator=( HANDLE h ) ;
-
-private:
-  /**
-   * \invariant The handle is an open handle to some system resource.
-   */
-  HANDLE handle ;
-
-  /**
-   * Validation function for the handle. Invoked at both construction and assignment.
-   */
-  void validate_handle() ;
-
-  /**
-   * Copy constructor declared private and not defined.
-   *
-   * \par Implementation
-   *   Add "= delete" for C++11.
-   */
-  Windows_Handle( const Windows_Handle & ) ;
-
-  /**
-   * Copy assignment declared private and not defined.
-   *
-   * \par Implementation
-   *   Add "= delete" for C++11.
-   */
-  Windows_Handle operator=( const Windows_Handle & ) ;
-
-};
 
 //-------------------------------------------------------
 // exe_name_set: case-insensitive wide-string set
 //-------------------------------------------------------
 int wcscmpi( const wchar_t * s1, const wchar_t * s2 ) ;
 
 struct exe_name
 {
   /**
    * Pointer to wide-character string, which is supposed to be null-terminated.
@@ skipping 263 matching lines @@
   exception,      ///< Callback threw an exception and thereby terminated iteration.
   error           ///< Callback always return true but EnumWindows failed.
 } enumerate_windows_state ;
 
 /**
  * Data to perform a window enumeration, shared between the main function and the callback function.
  */
 template< class F >
 struct ew_data
 {
+  /**
+   * Function to be applied to each enumerated window.
+   */
   F & f ;
 
+  /**
+   * Completion status of the enumeration.
+   */
   enumerate_windows_state status ;
 
+  /**
+   * An exception to be transported across the callback.
+   *
+   * The enumerator and the callback are not guaranteed to share a call stack,
+   *   nor need they even share compatible exception conventions,
+   *   and might not even be in the same thread.
+   * Thus, if the applied function throws an exception, 
+   *   we catch it in the callback and re-throw it in the enumerator.
+   * This member holds such an exception.
+   *
+   * This member holds an exception only if 'status' has the value 'exception'.
+   * Otherwise it's a null pointer.
+   */
   std::unique_ptr< std::exception > ee ;
 
+  /**
+   * Ordinary constructor.
+   */
   ew_data( F & f )
     : f( f ), status( started )
   {}
 } ;
 
 /**
  * Callback function for EnumWindows.
+ *
+ * This function provides two standard behaviors.
+ * It records early termination of the enumeration, should that happen by the applied function returning false.
+ * It captures any exception thrown for transport back to the enumerator.
  */
 template< class F >
 BOOL CALLBACK enumeration_callback( HWND window, LPARAM x )
 {
   // LPARAM is always the same size as a pointer
   ew_data< F > * data = reinterpret_cast< ew_data< F > * >( x ) ;
+  /*
+   * Top-level try statement prevents exception from propagating back to system.
+   */
   try 
   {
     bool r = data -> f( window ) ;
     if ( ! r )
     {
       data -> status = early ;
     }
     return r ;
   }
   catch ( std::exception e )
   {
     data -> ee = std::unique_ptr< std::exception >( new( std::nothrow ) std::exception( e ) ) ;
     data -> status = exception ;
     return FALSE ;
   }
   catch ( ... )
   {
+    data -> ee = std::unique_ptr< std::exception >() ;
     data -> status = exception ;
     return FALSE ;
   }
-  return TRUE ;
 }
 
 /**
  * Enumerate windows, applying a function to each one.
  */
 template< class F >
 bool enumerate_windows( F f )
 {
   ew_data< F > data( f ) ;
   BOOL x( ::EnumWindows( enumeration_callback< F >, reinterpret_cast< LPARAM >( & data ) ) ) ;
@@ skipping 134 matching lines @@
   }
 
   /*
    * Shut down every process in the pid_set.
    */
   bool shut_down() ;
 
 } ;
 
 #endif