= FDO RFC 47 - Add Interlocked Thread Support to FdoIDisposable =

This page contains an change request (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date||Jan. 14, 2010||
||Last Modified||Greg Boone [[Timestamp]]||
||Author||Greg Boone||
||RFC Status||Ready for Review|| 
||Implementation Status||Adopted||
||Proposed Milestone||3.5.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''|| ||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||

 
== Overview ==

The !AddRef / Release / !GetRefCount methods on FdoIDisposable are not currently thread-safe.  As a consequence the m_refCount data member can get corrupted if two separate threads simultaneously call any of these methods on the same object.  This is known to happen during garbage collection of Managed FDO objects.  Because the managed objects implement a finalizer, they are processed by a separate GC finalizer thread.  So while the GC finalizer thread is releasing ref counts on unmanaged objects, the main thread can be simultaneously modifying ref-counts on those same objects.

== Proposed Solution ==

In !MapGuide this issue is addressed by having all the unmanaged API classes extend from !MgGuardDisposable, which uses a mutex to limit access to the ref-count member to one thread at a time.  

A similar solution will be implemented for the FDO API, with a slight variation. The FDO API will use !InterlockedIncrement and !InterlockedDecrement as opposed to a mutex. Also, the use of these thread safe functions will be limited to FDO objects that are wrapped by a Managed object wrapper.

Here are the detailed steps that will need to be taken to implement the solution:

    * Add a flag to FdoIDisposable (Boolean member variable) to indicate if Interlocked support should be enabled for FDO disposable objects
    * Add a pure virtual method on FdoIDispoable that will indicate if Interlocked access should be enabled. E.g. bool !EnableInterlocked()
    * Add Interlocked calls to !AddRef, Release, and !GetRefCount that will only be if the boolean flag set by !EnableInterlocked() is True.
    * Change the Managed FDO API's MgFdoIDisposable class to call !EnableInterlocked whenever creating an FDO managed wrapper object around an FDO unmanaged object.

This solution should provide thread safe access for clients using the FDO Managed API while allowing those who use the unmanaged FDO API directly to avoid the added overhead of Interlocked support.

Managed API callers will experience some performance impact as outlined below. All clients will incur a larger memory allocation/overhead due to the addition of the Boolean variable.

NOTE: Timing tests were made to test the impact of implementing an Interlocked strategy vs using a Mutex. The testing involved repeatedly calling !AddRef and Release on a single unmanaged FDO object. 100 million repetitions (100 million !AddRef and 100 million Release calls) were done using a release build. 3 different cases were tried:

    * Unguarded !AddRef and Release (as is now)
    * !AddRef and Release guarded by Mutex
    * !AddRef and Release implemented by !InterlockedIncrement and !InterlockedDecrement.

The times in seconds were:

    * Unguarded:   0.876 sec
    * With Mutex:  4.034 sec
    * Interlocked: 2.314 sec


== Test Plan ==
Unit Testing and System testing using OSGeo !MapGuide

== Funding/Resources ==

Autodesk to provide resources / funding.