Concurrency Visualizer SDK

Article
03/10/2023

You can instrument your source code by using the Concurrency Visualizer SDK to display additional information in the Concurrency Visualizer. You can associate the additional data with phases and events in your code. These additional visualizations are known as markers. For an introductory walkthrough, see Introducing the Concurrency Visualizer SDK.

Properties

Flags, spans, and messages each have two properties: category and importance. In the Advanced Settings dialog box, you can use these properties to filter the set of markers that are displayed. In addition, these properties affect the visual representation of markers. For example, the size of flags is used to represent importance. In addition, color is used to indicate category.

Basic usage

The Concurrency Visualizer exposes a default provider that you can use to generate markers. The provider is already registered together with the Concurrency Visualizer and you don't have to do anything else to make the markers appear in the UI.

C# and Visual Basic

In C#, Visual basic, and other managed code, use the default provider by calling methods in the Markers class. It exposes four methods for generating markers: WriteFlag, EnterSpan, WriteMessage, and WriteAlert. There are multiple overloads for these functions, depending on whether you want to use defaults for the properties. The simplest overload takes only a string parameter that specifies the description of the event. The description is displayed in the Concurrency Visualizer reports.

To add SDK support to a C# or Visual Basic project

On the menu bar, choose Analyze, Concurrency Visualizer, Add SDK to project.
Select the project in which you want to access the SDK and then choose the Add SDK to Selected Project button.

Add an imports or using statement to your code.

using Microsoft.ConcurrencyVisualizer.Instrumentation;

Imports Microsoft.ConcurrencyVisualizer.Instrumentation

C++

In C++, create a marker_series Class object and use it to call functions. The marker_series class exposes three functions for generating markers, the marker_series::write_flag Method, the marker_series::write_message Method, and the marker_series::write_alert Method.

To add SDK support to a C++ or C project

On the menu bar, choose Analyze, Concurrency Visualizer, Add SDK to project.
Select the project in which you want to access the SDK and then choose the Add SDK to Selected Project button.
For C++, include cvmarkersobj.h. For C, include cvmarkers.h.

Add a using statement to your code.

using namespace Concurrency::diagnostic;

Create a marker_series object and pass it to the span constructor.


marker_series mySeries;
span s(mySeries, _T("Span description"));

Custom usage

For advanced scenarios, the Concurrency Visualizer SDK exposes more control. Two main concepts are associated with more advanced scenarios: marker providers and marker series. Marker providers are different ETW providers (each has a different GUID). Marker series are serial channels of events that are generated by one provider. You can use them to organize the events that are generated by a marker provider.

To use a new marker provider in a C# or Visual Basic project

Create a MarkerWriter object. The constructor takes a GUID.
To register the provider, open the Concurrency Visualizer Advanced Settings dialog box. Select the Markers tab and then choose the Add New Provider button. In the Advanced Settings dialog box, enter the GUID that was used to create the provider and a description of the provider.

To use a new marker provider in a C++ or C project

Use the CvInitProvider function to initialize a PCV_PROVIDER. The constructor takes a GUID* and PCV_PROVIDER*.
To register the provider, open the Advanced Settings dialog box. Select the Markers tab and then choose the Add New Provider button. In this dialog box, enter the GUID that was used to create the provider and a description of the provider.

To use a marker series in a C# or Visual Basic project

To use a new MarkerSeries, first create it by using a MarkerWriter object, and then generate marker events directly from the new series.

MarkerSeries series1 = myMarkerWriter.CreateMarkerSeries("Series 1");
series1.WriteFlag("My flag");

Dim series1 As New myMarkerWriter.CreateMarkerSeries("Series 1")
series1.WriteFlag("My flag")

To use a marker series in a C++ project

Create a marker_series object. You can generate events from this new series.
```
marker_series series;
series.write_flag(_T("Hello world!"));
```

To use a marker series in a C project

Use the CvCreateMarkerSeries function to create a PCV_MARKERSERIES.

PCV_MARKERSERIES series;
CvCreatemarkerSeries(myProvider, _T("My Series"), &series);
CvWriteFlag(series, _T("Writing a flag"));

Title	Description
C++ library reference	Describes the Concurrency Visualizer API for C++.
C library reference	Describes the Concurrency Visualizer API for C.
Instrumentation	Describes the Concurrency Visualizer API for managed code.
Concurrency Visualizer	Reference information for the views and reports of profiling data files that are generated by using the concurrency method and that include thread execution data.

Share via