Asynchronous Mode
- 6 minutes to read
The PivotGridControl can perform data-aware operations (retrieving data from the server, sorting, grouping, filtering data and calculating summaries) in a background thread, allowing the entire application to stay responsive while these operations are in progress.
Overview
If the Pivot Grid Control is working with a large dataset, retrieving data from a data source as well as performing various data-aware operations, such as sorting or filtering data, may take a considerable amount of time. In a standard (synchronous) mode, the entire application would not respond to user actions until the Pivot Grid Control completes the required operations, since the primary UI thread is busy. End-users may notice a small or considerable application freeze.
In asynchronous mode, only the Pivot Grid Control is frozen. The application continues interacting with an end-user, while the control processes data in a background thread. While processing data, the Pivot Grid Control displays a loading panel to indicate that this control is busy, and will not respond to user actions until the operation is completed.
Asynchronous Operations
End-User Operations
You can specify whether data-aware operations caused by end-user actions run synchronously or asynchronously. To do this, use the PivotGridOptionsBehaviorBase.UseAsyncMode property. If this property is set to true, all operations performed via the UI are asynchronous.
Operations Run In Code
In code, you can perform both synchronous and asynchronous operations, regardless of the UI settings. All methods whose names end with …Async are asynchronous, i.e., they start executing the related operation in a background thread and return control.
The Pivot Grid Control does not allow the calling of asynchronous methods while an asynchronous operation is in progress. You can check the PivotGridControl.IsAsyncInProgress property to determine whether or not an asynchronous operation is in progress. The PivotGridControl.UserAction property returns which operation is performed.
Note
You can perform a data-aware operation asynchronously even if there is no special …Async method implemented. The Pivot Grid Control provides the PivotGridControl.EndUpdateAsync method, which allows you to apply the changes made to the control in a background thread. For instance, you can customize the Pivot Grid Control via its properties, wrap the code in the PivotGridControl.BeginUpdate and PivotGridControl.EndUpdateAsync method calls, and the control will be updated asynchronously.
To ensure that the PivotGridControl.EndUpdateAsync method is executed even if an exception occurs, wrap calls to the PivotGridControl.BeginUpdate and PivotGridControl.EndUpdateAsync methods in a try..finally statement.
Note that you cannot start a data-aware operation in code while another operation is running in a background thread.
Subsequent Actions and Operation Result
Each asynchronous method has an overload that allows you to specify custom actions to be performed after the asynchronous operation is completed. To do this, pass an AsyncCompletedHandler delegate that performs the required actions as the asyncCompleted parameter.
If an asynchronous method returns data (an operation result), you must pass a delegate to obtain this data. The delegate’s result parameter returns an AsyncOperationResult instance. Use the AsyncOperationResult.Value property to obtain the operation result, and the AsyncOperationResult.Exception property to determine whether or not an exception has been thrown during operation execution.
Execution of Asynchronous Operations
The Pivot Grid Control performs the following actions after an asynchronous operation has been triggered:
- closes all popup menus and windows, disables the UI and loses focus (if it was focused);
- raises the PivotGridControl.AsyncOperationStarting event;
- locks access to pivot grid data through an API, shows a loading panel and runs background calculations.
After background calculations are finished, the Pivot Grid Control does the following:
- unlocks access to pivot grid data through an API, hides the loading panel and activates the UI;
- raises the PivotGridControl.AsyncOperationCompleted event;
- performs internal handling of the operation results;
- executes a custom delegate (if one has been passed).
Event Handling Specifics
In an asynchronous mode, custom painting events are raised before the pivot grid is displayed, and handled in the primary thread while the pivot grid is performing background calculations. This applies to the following events.
- PivotGridControl.CustomAppearance
- PivotGridControl.CustomDrawCell
- PivotGridControl.CustomDrawEmptyArea
- PivotGridControl.CustomDrawFieldHeader
- PivotGridControl.CustomDrawFieldHeaderArea
- PivotGridControl.CustomDrawFieldValue
- PivotGridControl.FieldValueImageIndex
For thread safety, you cannot directly access event data while an asynchronous operation is being executed. Otherwise, an exception will be thrown.
When handling custom painting events, use the pivot grid’s IThreadSafeAccessible.IsAsyncInProgress property to determine whether the pivot grid is performing background calculations. If this property returns false, you can access event data as you would normally do. Otherwise, you should use a thread-safe event parameter to access it.
Use the event parameter’s ThreadSafeArgs property to obtain a thread-safe event parameter. It provides read-only access to basic event parameter members, allowing you to obtain event data when an asynchronous operation is in progress. Event parameter members that cannot be accessed during asynchronous operation do not have corresponding thread-safe event parameter members.
Note
When handling custom painting events, you cannot use PivotGridControl members to access pivot grid data. Use the IThreadSafeAccessible interface members implemented by the PivotGridControl class instead. They allow you to obtain field and group collections, as well as text displayed in field value and data cells.
Member Tables
This section lists methods exposed by the Pivot Grid Control that perform various operations asynchronously.
Data Binding
| Method | Description |
|---|---|
| PivotGridControl.RefreshDataAsync | Reloads data from the control data source and recalculates summaries asynchronously. |
| PivotGridControl.RetrieveFieldsAsync | Creates PivotGridField objects for all fields in a data source asynchronously. |
| PivotGridControl.SetDataSourceAsync | Sets a data source for Pivot Grid Control and loads data asynchronously. |
| PivotGridControl.SetOLAPConnectionStringAsync | Sets a connection string to a cube in an MS Analysis Services database, and loads data from the cube asynchronously. |
Sorting
| Method | Description |
|---|---|
| PivotGridControl.ChangeFieldSortOrderAsync | Toggles the sort order of the specified field asynchronously. |
| PivotGridControl.ClearFieldSortingAsync | Clears field sorting asynchronously in OLAP mode. |
| PivotGridControl.SetFieldSortingAsync | Sets the specified sort order for the specified field asynchronously. |
Layout Operations
| Method | Description |
|---|---|
| PivotGridControl.ChangeFieldExpandedAsync | Expands or collapses all values of the specified field asynchronously. |
| PivotGridControl.CollapseAllAsync | Collapses all columns and rows in a Pivot Grid Control asynchronously. |
| PivotGridControl.CollapseAllColumnsAsync | Collapses all columns asynchronously. |
| PivotGridControl.CollapseAllRowsAsync | Collapses all rows asynchronously. |
| PivotGridControl.CollapseValueAsync | Collapses the specified column or row asynchronously. |
| PivotGridControl.ExpandAllAsync | Expands all columns and rows in the Pivot Grid Control asynchronously. |
| PivotGridControl.ExpandAllColumnsAsync | Expands all columns asynchronously. |
| PivotGridControl.ExpandAllRowsAsync | Expands all rows asynchronously. |
| PivotGridControl.ExpandValueAsync | Expands the specified column or row asynchronously. |
Drill-Down Operations
| Method | Description |
|---|---|
| PivotGridControl.CreateDrillDownDataSourceAsync | Returns a list of records used to calculate summary values for all cells asynchronously. |
| PivotGridControl.CreateOLAPDrillDownDataSourceAsync | Obsolete. In OLAP mode, returns a list of records used to calculate a summary value for the specified cell asynchronously. Allows you to specify which columns should be returned. |
Control Update
| Method | Description |
|---|---|
| PivotGridControl.EndUpdateAsync | Unlocks the Pivot Grid Control after the PivotGridControl.BeginUpdate method call, and starts an asynchronous update. |