Asynchronous Mode
- 6 minutes to read
Overview
If the Pivot Grid operates with a large dataset, data-aware operations such as data retrieval, sorting, and filtering may take a long time. In synchronous mode, the entire application does not respond to user actions until the Pivot Grid completes the operations because the main UI thread is busy. Users may notice an application freeze.
In asynchronous mode, only the Pivot Grid is frozen. The application continues to respond to user actions while the control processes data in a background thread. The Pivot Grid displays a loading panel to indicate the control is busy. The control does not respond to user actions until the operation finishes.
The picture below demonstrates asynchronous operations – the window does not freeze and responds to user actions while the Pivot Grid recalculates the data.
PivotGridControl allows the application to stay responsive while the following asynchronous operations are running in the background thread:
- Data Retrieval
- Data Grouping
- Data Filtering
- Summary Calculations
Asynchronous Operation Execution
After an asynchronous operation starts, the Pivot Grid executes the following actions:
- Closes all popup menus and windows, disables the UI and loses focus.
- Raises the PivotGridControl.AsyncOperationStarting event.
- Locks access to the Pivot Grid’s data through an API, displays a loading panel, and runs background calculations.
After background calculations are finished, the Pivot Grid does the following:
- Unlocks access to the Pivot Grid’s data through an API, hides the loading panel, and activates the UI.
- Raises the PivotGridControl.AsyncOperationCompleted event.
- Executes internal handling of the operation result.
Run Asynchronous Operations
Operations in the UI
You can specify how the Pivot Grid processes user actions - synchronously or asynchronously. Set the PivotGridOptionsBehaviorBase.UseAsyncMode property to true to enable asynchronous mode and make all operations initiated with the UI asynchronous.
The PivotGridControl.UserAction property indicates what operation the user executes.
Operations In Code
In code, you can execute both synchronous and asynchronous operations, regardless of the UI settings. Use the following techniques to execute operations asynchronously:
- Methods with the “Async” postfix
- All methods with the “Async” postfix are asynchronous. It means that they start operation in a background thread and return the control to the caller.
- The
BeginUpdate–EndUpdateAsyncmethod pair - Enclose the code that should be executed asynchronously in the PivotGridControl.BeginUpdate – PivotGridControl.EndUpdateAsync method pair. To ensure that the changes apply in case of an exception, wrap it in a “try .. finally” statement.
The Pivot Grid allows you to call multiple asynchronous operations simultaneously. However, if you need to call asynchronous methods individually and wait for them to complete, use the PivotGridControl.IsAsyncInProgress property. This property determines whether an asynchronous operation is in progress.
Warning
You cannot start a data-aware operation in code while another operation runs in a background thread.
Refer to the following section for asynchronous methods for the Pivot Grid: Related API.
How Events are Handled in Asynchronous Mode
In asynchronous mode, custom painting events occur before the Pivot Grid is displayed. They are handled in the main thread while the Pivot Grid executes background calculations. This behavior applies to the following events:
- PivotGridControl.CustomAppearance
- PivotGridControl.CustomDrawCell
- PivotGridControl.CustomDrawEmptyArea
- PivotGridControl.CustomDrawFieldHeader
- PivotGridControl.CustomDrawFieldHeaderArea
- PivotGridControl.CustomDrawFieldValue
- PivotGridControl.CustomFieldValueCells
- PivotGridControl.FieldValueImageIndex
Access Event Data
For thread safety, you cannot directly access event data while an asynchronous operation is being executed. Otherwise, an exception is thrown.
When you handle custom painting events, use the Pivot Grid’s IThreadSafeAccessible.IsAsyncInProgress property to determine whether the Pivot Grid executes background calculations. If this property returns false, you can access event data. Otherwise, you should use the e.ThreadSafeArgs thread-safe event parameter to access event data.
The e.ThreadSafeArgs property gives read-only access to basic event parameter members and allows 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.
Access Control Data
When you handle custom painting events, you cannot use PivotGridControl members to access Pivot Grid’s 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 a field value and data cells.
Related API
This section lists the Pivot Grid control’s methods that execute operations asynchronously.
Data Binding
- PivotGridControl.RefreshDataAsync
- Reloads data from the control data source and recalculates summaries asynchronously.
- PivotGridControl.RetrieveFieldsAsync
- Creates PivotGridField objects for all columns in a data source asynchronously.
- PivotGridControl.SetDataSourceAsync
- Sets the data source for the 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
- PivotGridControl.ChangeFieldSortOrderAsync
- Toggles the sort order of the specified field asynchronously.
- PivotGridControl.ClearFieldSortingAsync
- Clears field sorting asynchronously in OLAP mode.
- PivotGridControl.SetFieldSortingAsync
- Sets the sort order for the specified field asynchronously.
Layout Operations
- PivotGridControl.ChangeFieldExpandedAsync
- Expands or collapses all values of the specified Pivot Grid 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
- PivotGridControl.CreateDrillDownDataSourceAsync
- Returns a list of records used to calculate a summary value for the specified cell asynchronously.
Control Update
- PivotGridControl.EndUpdateAsync
- Unlocks the Pivot Grid control after the PivotGridControl.BeginUpdate method call, and starts an asynchronous update.
Example
The code snippet below shows how to create a drill-down data source for the selected Pivot Grid cell and display the resulting data source in the DrillDownForm dialog in asynchronous mode.
using DevExpress.XtraEditors;
using DevExpress.XtraPivotGrid;
using System;
using System.Windows.Forms;
namespace DxSampleOLAP {
public partial class OLAPDrillDownUserControl : XtraUserControl {
public OLAPDrillDownUserControl() {
InitializeComponent();
pivotGridControl.OptionsBehavior.UseAsyncMode = true;
// ...
pivotGridControl.CellDoubleClick += async (s, e) => {
try {
pivotGridControl.LoadingPanelVisible = true;
PivotDrillDownDataSource ds = await e.CreateDrillDownDataSourceAsync();
pivotGridControl.LoadingPanelVisible = false;
using(DrillDownForm form = new DrillDownForm(ds))
form.ShowDialog();
} catch(Exception ex) {
pivotGridControl.LoadingPanelVisible = false;
XtraMessageBox.Show(ex.Message);
}
};
}
}
}