Writing multithreaded ArcObjects code

In this topic

• About multithreading
• Using multithreading
• ArcObjects threading model
• Multithreading scenarios
  • Running lengthy operations on a background thread
  • Implementing stand-alone ArcObjects applications
  • Using managed ThreadPool and BackGroundWorker threads
  • Synchronizing execution of concurrent running threads
  • Sharing a managed type across multiple threads
  • Updating the UI from a background thread
  • Calling ArcObjects from a thread other than the main thread
  • Multithreading with geoprocessing

About multithreading

Using multithreading

ArcObjects threading model

Multithreading scenarios

Running lengthy operations on a background thread

• According to the Thread in Isolation model, you cannot share ArcObjects components between threads. Instead, take advantage of the fact that singleton objects are "per thread" and, in the background thread, instantiate all factories required to open FeatureClasses, create new FeatureClasses, set spatial references, and so on.
• All information passed to the thread must be in the form of simple types or managed types.
• In cases where you must pass ArcObjects components from the main thread into a worker thread, serialize the object into a string, pass the string to the target thread, and deserialize the object back. For example, you can use XmlSerializerClass to serialize an object, such as workspace connection properties (an IPropertySet), into a string; pass the string with the connection properties to the worker thread; and deserialize the connection properties on the worker thread using the XmlSerializerClass. This way, the connection properties object are created on the background thread, and cross-apartment calls are avoided.
• While running the background thread, you can report the task progress onto a UI dialog box. This is covered in more detail in the Updating the UI from a background thread section of this topic.

// Generate the thread that populates the locations table.
Thread t=new Thread(new ThreadStart(PopulateLocationsTableProc));
// Mark the thread as a single threaded apartment (STA) to efficiently run ArcObjects.
t.SetApartmentState(ApartmentState.STA);
// Start the thread.
t.Start();

/// <summary>
/// Load the information from the MajorCities feature class to the locations table.
/// </summary>
private void PopulateLocationsTableProc()
{
    //Get the ArcGIS path from the registry.
    RegistryKey key=Registry.LocalMachine.OpenSubKey(@"SOFTWARE\ESRI\ArcGIS");
    string path=Convert.ToString(key.GetValue("InstallDir"));

    //Open the feature class. The workspace factory must be instantiated 
    //since it is a singleton per thread. 
    IWorkspaceFactory wf=new ShapefileWorkspaceFactoryClass()as IWorkspaceFactory;
    IWorkspace ws=wf.OpenFromFile(System.IO.Path.Combine(path, @
        "DeveloperKit10.0\Samples\Data\USZipCodeData"), 0);
    IFeatureWorkspace fw=ws as IFeatureWorkspace;
    IFeatureClass featureClass=fw.OpenFeatureClass(m_sShapefileName);

    //Map the name and ZIP Code fields.
    int zipIndex=featureClass.FindField("ZIP");
    int nameIndex=featureClass.FindField("NAME");
    string cityName;
    long zip;

    try
    {
        //Iterate through the features and add the information to the table.
        IFeatureCursor fCursor=null;
        fCursor=featureClass.Search(null, true);
        IFeature feature=fCursor.NextFeature();
        int index=0;

        while (null != feature)
        {
            object obj=feature.get_Value(nameIndex);
            if (obj == null)
                continue;
            cityName=Convert.ToString(obj);

            obj=feature.get_Value(zipIndex);
            if (obj == null)
                continue;
            zip=long.Parse(Convert.ToString(obj));
            if (zip <= 0)
                continue;

            //Add the current location to the locations table.
            //m_locations is a DataTable that contains the cities and ZIP Codes. 
            //It is defined in the full code before this excerpt starts.
            DataRow r=m_locations.Rows.Find(zip);
            if (null == r)
            {
                r=m_locations.NewRow();
                r[1]=zip;
                r[2]=cityName;
                lock(m_locations)
                {
                    m_locations.Rows.Add(r);
                }
            }

            feature=fCursor.NextFeature();

            index++;
        }

        //Release the feature cursor.
        Marshal.ReleaseComObject(fCursor);
    }
    catch (Exception ex)
    {
        System.Diagnostics.Trace.WriteLine(ex.Message);
    }
}

Implementing stand-alone ArcObjects applications

namespace ConsoleApplication1
{
    class Program
    {
        [STAThread] static void Main(string[] args)
        {
            // ...
        }
    }
}

Using managed ThreadPool and BackGroundWorker threads

/// <summary>
/// Class used to pass the task information to the working thread.
/// </summary>
public class TaskInfo
{
    ... public TaskInfo(int BandID, ManualResetEvent doneEvent)
    {
        m_bandID=BandID;
        m_doneEvent=doneEvent;
    }
    ...
}

... public override void OnMouseDown(int Button, int Shift, int X, int Y)
{
    ... 
    // Run the subset thread that will spin off separate subset tasks. 
    //By default, this thread will run as MTA.
    // This is needed to use WaitHandle.WaitAll(). The call must be made
    // from MTA.
    Thread t=new Thread(new ThreadStart(SubsetProc));
    t.Start();
}

/// <summary>
/// Main subset method.
/// </summary>
private void SubsetProc()
{
    ... 
    //Create a dedicated thread for each band of the input raster.
    //Create the subset threads.
    Thread[] threadTask=new Thread[m_intBandCount];

    //Each thread will subset a different raster band. 
    //All information required for subsetting the raster band will be 
    //passed to the task by the user-defined TaskInfo class.
    for (int i=0; i < m_intBandCount; i++)
    {
        TaskInfo ti=new TaskInfo(i, doneEvents[i]);
        ... 
        // Assign the subsetting thread for the rasterband.
        threadTask[i]=new Thread(new ParameterizedThreadStart(SubsetRasterBand));
        // Note the STA that is required to run ArcObjects.
        threadTask[i].SetApartmentState(ApartmentState.STA);
        threadTask[i].Name="Subset_" + (i + 1).ToString();
        // Start the task and pass the task information.
        threadTask[i].Start((object)ti);
    }
    ... 
    // Wait for all threads to complete their task…
    WaitHandle.WaitAll(doneEvents);
    ...
}

/// <summary>
/// Subset task method.
/// </summary>
/// <param name="state"></param>
private void SubsetRasterBand(object state)
{
    // The state object must be cast to the correct type, because the
    // signature of the WaitForTimerCallback delegate specifies type
    // Object.
    TaskInfo ti=(TaskInfo)state;

    //Deserialize the workspace connection properties.
    IXMLSerializer xmlSerializer=new XMLSerializerClass();
    object obj=xmlSerializer.LoadFromString(ti.InputRasterWSConnectionProps, null,
        null);

    IPropertySet workspaceProperties=(IPropertySet)obj;
    ...
}

Synchronizing execution of concurrent running threads

• System.Threading.Thread—Used to create and control threads, change priority, and get status.
• System.Threading.WaitHandle—Defines a signaling mechanism to indicate taking or releasing exclusive access to a shared resource, allowing you to restrict access to a block of code.
  • Calling the WaitHandle.WaitAll() method must be done from an MTA thread. To run multiple synchronized tasks, you first have to run a worker thread that, in turn, will run the multiple threads.
• System.Threading.Monitor—Similar to System.Threading.WaitHandle and provides a mechanism that synchronizes access to objects.
• System.Threading.AutoResetEvent and System.Threading.ManualResetEvent—Used to notify waiting threads that an event has occurred, allowing threads to communicate with each other by signaling.

/// <summary>
/// Class used to pass the task information to the working thread.
/// </summary>
public class TaskInfo
{
    //Signal the main thread that the thread has finished its task.
    private ManualResetEvent m_doneEvent;
    ... public TaskInfo(int BandID, ManualResetEvent doneEvent)
    {
        m_bandID=BandID;
        m_doneEvent=doneEvent;
    }
    ... public ManualResetEvent DoneEvent
    {
        get
        {
            return m_doneEvent;
        }
        set
        {
            m_doneEvent=value;
        }
    }
}



//Block access to the shared resource (raster dataset).
private static AutoResetEvent m_autoEvent=new AutoResetEvent(false);

... public override void OnMouseDown(int Button, int Shift, int X, int Y)
{
    ... 
    // Run the subset thread that will spin off separate subset tasks. 
    // By default, this thread will run as MTA.
    // This is needed because to use WaitHandle.WaitAll(), the call must be made
    // from MTA.
}

/// <summary>
/// Main subset method.
/// </summary>
private void SubsetProc()
{
    ... 
    //Create ManualResetEvent to notify the main threads that
    //all ThreadPool threads are done with their tasks.
    ManualResetEvent[] doneEvents=new ManualResetEvent[m_intBandCount];

    //Create a ThreadPool task for each band of the input raster.
    //Each task will subset a different raster band. 
    //All information required for subsetting the raster band will be 
    //passed to the ThreadPool task by the user-defined TaskInfo class.
    for (int i=0; i < m_intBandCount; i++)
    {
        //Create the ManualResetEvent field for the task to 
        // signal the waiting thread that the task had been completed.
        doneEvents[i]=new ManualResetEvent(false);

        TaskInfo ti=new TaskInfo(i, doneEvents[i]);
        ... 
        // Assign the subsetting thread for the rasterband.
        threadTask[i]=new Thread(new ParameterizedThreadStart(SubsetRasterBand));
        // Note the STA, which is required to run ArcObjects.
        threadTask[i].SetApartmentState(ApartmentState.STA);
        threadTask[i].Name="Subset_" + (i + 1).ToString();
        // Start the task and pass the task information.
        threadTask[i].Start((object)ti);
    }

    //Set the state of the event to signaled to allow one or more of the 
    //waiting threads to proceed.
    m_autoEvent.Set();

    // Wait for all threads to complete their task…
    WaitHandle.WaitAll(doneEvents);
    ...
}

/// <summary>
/// Subset task method.
/// </summary>
/// <param name="state"></param>
private void SubsetRasterBand(object state)
{
    // The state object must be cast to the correct type, because the signature 
    // of the WaitOrTimerCallback delegate specifies type Object.
    TaskInfo ti=(TaskInfo)state;
    ... 

    //Lock all other threads to get exclusive access.
    m_autoEvent.WaitOne();

    //Insert code containing your threading logic here.

    //Signal the next available thread to get write access.
    m_autoEvent.Set();

    //Signal the main thread that the thread has finished its task.
    ti.DoneEvent.Set();
}

Sharing a managed type across multiple threads

 

private DataTable m_locations=null;
... 

DataRow rec=m_locations.NewRow();
rec["ZIPCODE"]=zipCode; //ZIP Code. 
rec["CITYNAME"]=cityName; //City name.

//Lock the table and add the new record.
lock(m_locations)
{
    m_locations.Rows.Add(rec);
}

Updating the UI from a background thread

1. In the user form, declare a delegate through which you will pass the information to the control:

public class WeatherItemSelectionDlg: System.Windows.Forms.Form
{
    private delegate void AddListItmCallback(string item);
    ...

//Make thread-safe calls to Windows Forms Controls.
private void AddListItemString(string item)
{
    // InvokeRequired compares the thread ID of the
    //calling thread to the thread ID of the creating thread.
    // If these threads are different, it returns true.
    if (this.lstWeatherItemNames.InvokeRequired)
    {
        //Call itself on the main thread.
        AddListItmCallback d=new AddListItmCallback(AddListItemString);
        this.Invoke(d, new object[]
        {
            item
        }
        );
    }
    else
    {
        //Guaranteed to run on the main UI thread. 
        this.lstWeatherItemNames.Items.Add(item);
    }
}

private void PopulateSubListProc()
{
    //Insert code containing your threading logic here.

    //Add the item to the list box.
    frm.AddListItemString(data needed to update the UI control, string in this case )
        ;
}

//Generate a thread to populate the list with items that match the selection criteria.
Thread t=new Thread(new ThreadStart(PopulateSubListProc));
t.Start();

Calling ArcObjects from a thread other than the main thread

/// <summary>
/// A helper method used to delegate calls to the main thread.
/// </summary>
public sealed class InvokeHelper: Control
{
    //Delegate used to pass the invoked method to the main thread.
    public delegate void MessageHandler(NavigationData navigationData);

    //Class members.
    private IActiveView m_activeView;
    private IPoint m_point=null;

    /// <summary>
    /// Class constructor.
    /// </summary>
    /// <param name="activeView"></param>
    public InvokeHelper(IActiveView activeView)
    {
        //Make sure that the control was created and that it has a valid handle.
        this.CreateHandle();
        this.CreateControl();

        //Get the active view.
        m_activeView=activeView;
    }

    /// <summary>
    /// Delegate the required method onto the main thread.
    /// </summary>
    /// <param name="navigationData"></param>
    public void InvokeMethod(NavigationData navigationData)
    {
        // Invoke HandleMessage through its delegate.
        if (!this.IsDisposed && this.IsHandleCreated)
        Invoke(new MessageHandler(CenterMap), new object[]
        {
            navigationData
        }
        );
    }

    /// <summary>
    /// The method that gets executed by the delegate.
    /// </summary>
    /// <param name="navigationData"></param>
    public void CenterMap(NavigationData navigationData)
    {
        //Get the current map visible extent.
        IEnvelope envelope =
            m_activeView.ScreenDisplay.DisplayTransformation.VisibleBounds;
        if (null == m_point)
        {
            m_point=new PointClass();
        }

        //Set the new map center coordinate.
        m_point.PutCoords(navigationData.X, navigationData.Y);
        //Center the map around the new coordinate.
        envelope.CenterAt(m_point);
        m_activeView.ScreenDisplay.DisplayTransformation.VisibleBounds=envelope;
        //Rotate the map to the new rotation angle.
        m_activeView.ScreenDisplay.DisplayTransformation.Rotation =
            navigationData.Azimuth;
    }

    /// <summary>
    /// Control initialization.
    /// </summary>
    private void InitializeComponent(){}


    /// <summary>
    /// A user-defined data structure used to pass information to the Invoke method.
    /// </summary>
    public struct NavigationData
    {
        public double X;
        public double Y;
        public double Azimuth;

        /// <summary>
        /// Struct constructor.
        /// </summary>
        /// <param name="x">map x coordinate</param>
        /// <param name="y">map x coordinate</param>
        /// <param name="azimuth">the new map azimuth</param>
        public NavigationData(double x, double y, double azimuth)
        {
            X=x;
            Y=y;
            Azimuth=azimuth;
        } 

        /// <summary>
        /// This command triggers the tracking functionality.
        /// </summary>
        public sealed class TrackObject: BaseCommand
        {
            //Class members.
            private IHookHelper m_hookHelper=null;
            ... private InvokeHelper m_invokeHelper=null;
            private System.Timers.Timer m_timer=null;

            ... 

            /// <summary>
            /// Occurs when this command is created.
            /// </summary>
            /// <param name="hook">Instance of the application</param>
            public override void OnCreate(object hook)
            {
                ... 
                //Instantiate the timer.
                m_timer=new System.Timers.Timer(60);
                m_timer.Enabled=false;
                //Set the timer's elapsed event handler.
                m_timer.Elapsed += new ElapsedEventHandler(OnTimerElapsed);
            }

            /// <summary>
            /// Occurs when this command is clicked.
            /// </summary>
            public override void OnClick()
            {
                //Create the InvokeHelper class.
                if (null == m_invokeHelper)
                    m_invokeHelper=new InvokeHelper(m_hookHelper.ActiveView);
                ... 
                //Start the timer.
                if (!m_bIsRunning)
                    m_timer.Enabled=true;
                else
                    m_timer.Enabled=false;
                ...
            }

            /// <summary>
            /// Timer elapsed event handler.
            /// </summary>
            /// <param name="sender"></param>
            /// <param name="e"></param>
            private void OnTimerElapsed(object sender, ElapsedEventArgs e)
            {
                ... 
                //Create the navigation data structure.
                NavigationData navigationData=new NavigationData(currentPoint.X,
                    currentPoint.Y, azimuth);

                //Update the map extent and rotation.
                m_invokeHelper.InvokeMethod(navigationData);
                ...
            }

Multithreading with geoprocessing

• In ArcGIS Server 9.2 and above, use geoprocessing services. This enables the desktop to work with geoprocessing in an asynchronous execution mode and to run multiple geoprocessing tools asynchronously with each other. The mechanism to execute the server tool and listen for feedback is described in How to work with geoprocessing services.
• In ArcGIS 10, use the Geoprocessor.ExecuteAsync method. You can execute tools asynchronously to the ArcGIS application. This means that an ArcGIS for Desktop application or control (for example, MapControl, PageLayoutControl, GlobeControl, or SceneControl) remains responsive to user interaction while a tool is executed in a background process. In other words, data can be viewed and queried while a tool is executing input datasets. This is more fully described in Running a geoprocessing tool using background geoprocessing.

See Also: