View source for Analytica Decision Engine Reference/Release ADE Objects BEFORE deleting Analytica objects

[[Category: Analytica Decision Engine]]
[[Category: COM integration]]

__TOC__

==Programming Note==
When using [[Analytica Decision Engine]] (ADE), it is critical that your code releases any ADE objects before Analytica objects used by your code are deleted.  Failure to do so can result in a crash, and often the crash occurs much later so that it is hard to associate the crash with the original source of the problem.

Analytica objects may be deleted by
* Closing your model, CAEngine::CloseModel
* Deleting the object, via CAEngine::DeleteObject
* Deleting a module object that contains the object, via CAEngine::Delete
* Using a typescript command, such as delete, to delete the object.

It is fairly obviously which object CAObject, CAIndex instances point to.  These should be released BEFORE deleting the underlying object.  CATables also point to an underlying object, the result or definition object, but also to index objects.  If you delete any index object that belongs to the table, you need to release the CATable instance first!!

The following code demonstrates (non-.NET):

==Good code==
<pre style="background:white; border:white; margin-left: 1em;">
 CAObject obj = ade.Get("Va1")
 ....
 obj = Nothing
 ade.DeleteObject("Va1")
 obj = ade.Get("Va2")
 ....
</pre>

==Bad code==
<pre style="background:white; border:white; margin-left: 1em;">
 CAObject obj = ade.Get("Va1")
 ...
 ade.DeleteObject("Va1")
 obj = ade.Get("Va2")
 ...
</pre>

==Good .NET code==
<pre style="background:white; border:white; margin-left: 1em;">
 CAObject obj = ade.Get("Va1")
 ...
 System.Runtime.InteropServices.Marshal.ReleaseComObject(obj)                           ' In .NET, you must explicitly release
 obj = Nothing
 ade.DeleteObject("Va1")
 obj = ade.Get("Va2")
 ...
</pre>

== Closing models ==

When you load a model, operate on it with ADE for a while, odds are that you'll have several ADE objects instantiated -- perhaps some CAObjects, CATables, etc.  If you close that model and open another, it is very important that you release all the objects that were in use for the original model.

Here is a common mistake that can lead to a crash (much later):

<pre style="background:white; border:white; margin-left: 1em;">
 CATable tab = obj.ResultTable
 ...
 ade.CloseModel( )
 ade.OpenModel( "newModel.ana" )
 ...
 tab = ade.Get(name).ResultTable                       ' Reuse tab
</pre>

The CATable pointed to by ''tab'' is released in the last line, but this release occurs after the result object and indexes used by the CATable have ceased to exist.  The correct way is to release ''tab'' before closing the first model, and set tab to Nothing, e.g.:

<pre style="background:white; border:white; margin-left: 1em;">
 CATable tab = obj.ResultTable
 ...
 ReleaseComObject(obj)                                   ' If in .NET
 tab = Nothing
 ade.CloseModel( )
 ade.OpenModel( "newModel.ana" )
 ...
 tab = ade.Get(name).ResultTable                   ' Reuse tab
</pre>

== .NET notes ==

The whole COM release thing is a complete pain.  The reason for having to call ReleaseComObject is because the garbage collection architecture leaves the ADE object laying around until GC happens to run.  Instead of worrying about calling ReleaseComObject every time, you can just ensure that you've released the pointers by setting them to null, and then force a garbage collection before closing a model or otherwise deleting objects.  Code would look more like this:

<pre style="background:white; border:white; margin-left: 1em;">
 CATable tab = obj.ResultTable
 ...
 tab = Nothing
 ...
 System.GC.Collect()
 ade.CloseModel( )
 ade.OpenModel("newModel.ana")
 ...
 tab = ade.Get(name).ResultTable                                      ' Reuse tab
</pre>

If you follow this practice of garbage collecting before any operation that may delete an object, your .NET code can be much cleaner, especially in C# or C++/CLR (using deterministic destruction in the latter).

In C#, when you instantiate an object such as CATable, wrap it in a using block:

<pre style="background:white; border:white; margin-left: 1em;">
 Using ( CATable tab = obj.ResultTable ) 
 {
    // .. Do something with tab ...
 } 
</pre>

If you delete an object, or close a model, that would occur outside the lexical scope of tab.  So, the logical flow would look like this:

<pre style="background:white; border:white; margin-left: 1em;">
 Using ( CATable tab = obj.ResultTable ) 
 {
    // .. Do something with tab ...
 } 
 ...
 System.GC.Collect();
 ade.CloseModel( );
</pre>

The sequence of things that happens here:
* tab is instantiated
* Operations inside the using occur using tab
* When the end of the Using scope is reached, the interop wrapper tab is released by .NET. At this point it is still in the managed heap, ready to be collected.  But it still points to the CATable COM object, which still lives inside ADE, which still points to the Analytica objects.
* When System.GC.Collect() executes, the tab interop wrapper is garbaged collected.  At this time, ReleaseComObject completes, and the the CATable is released and freed inside ADE.  Now it is safe to delete objects.
* CloseModel deletes Analytica objects.

Religious use of the Using construct in C# will keep you from making an error that could result in a problem -- as long as you also remember to garbage collect prior to closing your model or deleting objects.

''Note that the need to release, and techniques discussed here, are not limited to ADE.  You should do the same for any COM component used in a .NET application -- especially if it is used out-of-process.''

A final note for those porting VB applications from VB6 into .NET: be sure to remove all "call sub()" syntaxes from your code, in favor of simply using "sub()" instead. When your subroutine instantiates COM objects, using call will orphan those objects and they cannot be released later, even using ReleaseComObject.

==See Also==
* [[Analytica Decision Engine]]
* [[COM Integration]]