View source for CAEngine::MonitorProcess

''(New to ADE 4.3)''

= [[CAEngine]]::MonitorProcess(long pid) =

Sets up a monitor thread inside the ADE instance to detect the termination of the process with the indicated process id, and to terminate the ADE process if the indicated pid terminates first.  The process must exist on the same computer that ADE is running on.

Use of this function can help to guarantee that ADE processes are terminated even when your own calling code terminates abnormally, such as when you stop the code prematurely while debugging, or when your program crashes.  

The COM protocol requires a caller to release each object that it uses, and out-of-process COM servers normally stay active until the last object is released.  In ADE's case, ADE will stay normally active until the calling process calls IUnknown::Release() on the object (a standard COM interface method).  A problem arises, however, when the calling process terminates prematurely, such as when it is killed during debugging or crashes. When that happens, the calling process never gets the chance to release the object, so ADE never gets the release signal, and thus continues to run.  (The same is true of any out-of-process COM server).

By calling this method immediately after you start an out-of-process instance of ADE, supplying it with your own program's process ID, it enables ADE to monitor the status of your process, and detect when it is terminated.  Normally, your process will release the last [[CAEngine]] instance so that ADE will terminate first.  But should that not happen, the ADE.exe process will automatically terminate itself at the moment it detects your process has terminated.

= Usage =

In VB.NET syntax, you would call this immediately following your acquisition of a [[CAEngine]], as follows:

 Dim ade As [[CAEngine]] = new CAEngine
 Dim pid As Long = System.Diagnostics.Process.GetCurrentProcess().Id
 ade.MonitorProcess(pid)

= Notes =

You cannot ''unmonitor'' a process.  Once a monitor is established, it will continue until ADE terminates.

You can call this multiple times with different pid.  When doing so, ADE will watch all indicated processes, and terminate itself if any of them terminate.

You can only monitor processes on the same machine that ADE.exe is running on.  If you are using a remote ADE.exe through DCOM, this doesn't work.

The process monitored does not have to be the calling process.  All you need is the pid for it.

Your security settings must be such that the ADE.exe process's account allows it permission to obtain a handle to the indicated process with SYNCHRONIZE permission (see [http://msdn.microsoft.com/en-us/library/ms684320(VS.85).aspx OpenProcess]] for more detail).  It would be unusual to not have this permission, but not impossible.

The method is not exposed in the the ADE 4.2 COM API, so "officially" you'll have to wait for the release of ADE 4.3.  However, there is a back door in patch release 4.2.3, in that it can be called through the Automation API.  Thus, from 4.2.3+ you could do this:

  Dim adeObj As Object = ade
  ade.MonitorProcess(System.Diagnostics.Process.GetCurrentProcess().Id)