I wanted to share with you that we are not planning any more updates to this blog beyond this last one, so feel free to unsubscribe.

For general news on diagnostics tools in Visual Studio we encourage you to monitor the VS Diagnostics home here: https://blogs.msdn.com/b/visualstudioalm/archive/tags/diagnostics/. I just posted there about the Concurrency Visualizer in VS2013.

While parsing the ETW events for the process being profiled, the visualizer looks for the thread start/end events. I used xperf to drill further into the ETW events in the ETL file collected by the Concurrency Visualizer. Here are some snippets from the xperf output (a csv file listing all the events collected in the ETL log):

T-Start, 1144863, application1.exe ( 572), 5868, …

T-End, 1155571, application1.exe ( 572), 5868, ….

T-Start, 37311946, application1.exe ( 572), 5868, …

T-End, 37361583, application1.exe ( 572), 5868, …

Here, the T-Start and T-End represent the thread start and thread end events. You can clearly see that thread ID 5868 has been assigned to two different threads within the same process application1.exe(Process ID 572).

In such cases, the Concurrency Visualizer will show the threads in separate channels. To distinguish the two threads, the thread ID entry is represented as “ThreadID#<int>”, where the integer suffix is the thread ID reuse count. The thread ID may be recycled multiple times within the same process: the integer suffix is incremented for each thread instance.

Refer to the following Threads View screenshot in the Concurrency Visualizer:

Thread IDs 5868 and 968 are being recycled. The channels with Thread ID 5868#2 and 968#2 represent the second threads reusing the same thread IDs.

The Cores View legend also visualizes the threads with the “ThreadID#<int>” representation. A sample view:

Next time you bump into these weird numbers with the #2, #3.. suffixes, you know what they mean. Happy profiling!

Note that I am using the Concurrency Visualizer SDK. This helps me quickly identify the thread and time interval corresponding to my file compress operation. For details on how to use the Concurrency Visualizer SDK to visualize events in your application, see “Introducing the Concurrency Visualizer SDK”.

After profiling my application with the Concurrency Visualizer, the following facts are quite clear:

1. Main Thread 9160, which happens to be the UI thread, is spending most of it ‘s time in Execution.

2. No UI processing is happening during the Compress file operation. 

During directed testing, this was fine for small files. As file sizes grew compression became a substantial overhead for the UI thread to handle. What this means is that I need to delegate the job of compression to another thread so that the UI thread could remain responsive during compression. This is a good opportunity to try out the new  .Net 4.5 Async features.

I quickly moved the compression job onto the ThreadPool using Task.Run. I also changed the Button_Click handler to an async handler, and I await the compression task in Button_Click. When Button_Click gets to the first await, control returns to the caller, thus unblocking the UI thread.

private async void Button_Click(object sender, RoutedEventArgs e)
{
    await Task.Run(() =>
    {
        // actual Compress code goes here 
    });

    // // code to run post Compress // }

Now with this small change, I see that the issue is resolved and I don’t see any unresponsive UI in my application. To confirm this, let us look at the Concurrency Visualizer output:

1. One can clearly see that the Main Thread 4896 is busy with UI processing  cycles.

2. Worker Thread 6496 is actually performing the compress operation.

3. Visible Timeline Profile shows that app is spending 50% of the time in UI processing, as opposed to 17% from the first attempt.

You might be wondering about the System.Threading.Tasks markers in the Concurrency Visualizer output. These are from the await and Task.Run operations. They are not enabled by default. To collect the markers for asynchronous operations under System.Threading.Tasks, one needs to change the marker provider level. Goto Visual Studio –> Analyze –> Concurrency Visualizer –> Advanced Settings –> Markers tab.

Select the System.Threading.Tasks provider and click the edit provider icon .

Set the “Collect events with this importance level and greater” to “Low” as shown in the above screenshot. Rerun your application and collect the trace. The Concurrency Visualizer will visualize the System.Threading.Tasks events as markers !!

However, please note that the individual task events can be verbose and cause performance problems. So users should apply some caution when opting to collect these events.

James Rapp

Be sure to Analyze the Collected Trace Before Moving them to Another Machine

After collecting the trace, analyze the trace on the same machine where it was collected.  If you analyze the trace on another machine, some call stacks may not resolve.  Use the Analyze command.

Copy the Files to the Machine with Visual Studio 11

After analysis completes there will be four files associated with the trace:

1. CVTrace file – This is the main file associated with your trace.  Visual Studio 11 recognizes this file and will open it.
2. CVData file – This file is generated after analysis and contains the processed data associated with the trace.
3. kernel.etl – This file contains raw trace data associated with kernel events.
4. user.etl – This file contains raw trace data associated with user-mode events.

If you collected the trace by launching an exe or attaching to a specific process, you only need to bring files 1 and 2 back to the machine with Visual Studio 11.  If you collected a system-wide trace (by using the Attach command without a process specified), then you need to bring all of the files back to the machine with Visual Studio 11.  This is because with a system-wide trace, you need to perform analysis on each new process you want to examine.  For analysis, you need files 3 and 4.

Open the CVTrace File From Visual Studio 11

Once  you’ve copied the necessary files back to the machine with Visual Studio 11, you merely need to open the CVTrace file.  You can do this using the File->open dialog in Visual Studio 11.  You can also use the Open Trace dialog under the Concurrency Visualizer menu:

James Rapp – Parallel Computing Platform

The answer to this question depends on whether you have a Visual Studio 11 DVD or whether you installed it from the web. 

Locating the Installer on the Visual Studio DVD

If you have the Visual Studio 11 DVD, you’ll find a top-level directory called “Concurrency Visualizer”.  The installer, “concvi_standalonecollection” is located here.

Locating the Installer When Visual Studio was Installed from the Web

If you do not have the Visual Studio 11 DVD, you can still obtain the installer for CVCollectionCmd.  Here is how:

1. Locate the Visual Studio 11 installer.  In my case, I downloaded the installer to c:\users\my name\downloads and the installer is “vs_ultimate.exe”.  The installer name will vary depending on the SKU you installed.
2. Open a command prompt, and navigate to the directory containing the Visual Studio 11 installer.
3. Type <installer name> /layout.  For me, the installer name is “vs_ultimate.exe”, so I type “vs_ultimate.exe /layout”
4. The dialog that appears will prompt you to choose a location where the downloaded files will be saved.  

This will download the non-installable files associated with Visual Studio 11.  Thus, after the download completes, you should now see a directory titled “Concurrency Visualizer” in the directory you specified during step 4.  This contains the CVCollectionCmd installer.

Deploying CVCollectionCmd

Now, you need to deploy CVCollectionCmd on the machine where you want to use it.

1. Copy the installer, “concvi_standalonecollection.exe”, to the machine you want to run it on.
2. Run the installer (you’ll need admin privileges).

(Note that using the installer is the recommended approach because it allows Microsoft to service CVCollectionCmd.  However, it may be possible to deploy the installer locally, and just xcopy the files to the machine on which you want to run CVCollectionCmd.)

You are now ready to use CVCollectionCmd.exe.  After deployment, this file is typically located under c:/Program Files/Microsoft Concurrency Visualizer Collection Tools (or c:/Program Files (x86)/Microsoft Concurrency Visualizer Collection Tools).

James Rapp – Parallel Computing Platform

Collecting a Trace

There are a few different ways to collect a trace.  If you are interested in visualizing data associated with a single process, you can either launch an executable under the Concurrency Visualizer or attach to a running process on the system.  You can also collect a system-wide trace if you want to choose a process to investigate after collection.

Launching an Executable Under CVCollectionCmd

To launch an executable under the CVCollectionCmd, use the Launch command.  For example,

CVCollectionCmd.exe /Launch “C:\Users\MyName\Documents\ConsoleApplication1.exe”

When I am finished collecting the trace, I need to detach:

CVCollectionCmd.exe /Detach 

Attaching to a Running Process

In this example, suppose I want to collect a trace on cmd.exe.  In my case cmd.exe is running under process ID (PID) 5520.  I can attach the Concurrency Visualizer to this process using the Attach command.  In this case, I need to supply the Attach command with the process I want to attach to (for this, use the /Process option).  I can either supply the name (if the name uniquely identifies the process) or the PID.  Therefore, I can type the following:

CVCollectionCmd.exe /Attach /Process cmd

Alternatively, I could refer to cmd.exe by its PID:

CVCollectionCmd.exe /Attach /Process 5520

Either way, I am now collecting data on this process.  When I am finished collecting the trace, I need to detach:

CVCollectionCmd.exe /Detach 

Collecting a System-Wide Trace

In some cases, you may prefer to trace all processes running on the system.  To do this, simply use the Attach command without specifying a single process:

CVCollectionCmd.exe /Attach

When you are finished collecting the trace, you need to detach:

CVCollectionCmd.exe /Detach

Analyzing a Trace

It is important to analyze the trace you collected on the same machine.  If you analyze on a different machine, you run the risk that the Concurrency Visualizer will not resolve some call stacks.  To analyze a trace you recently collected, first find the trace.  Typically, the trace is saved to the current directory of the command prompt you are using.  In my case, this happens to be c:/users/MyName.

When analyzing a trace, the Concurrency Visualizer processes raw trace data associated with a single process.  Therefore, you need to specify the process you want to analyze if you collected a system-wide trace.  If the trace is not system-wide, the process of interest is already known to the Concurrency Visualizer, so one need not specify it.

To analyze a trace, use the Analyze command and specify the location of the CVTrace file that was generated during collection.  For a system-wide trace, you also need to specify the process of interest.  In my case, I want to analyze data associated with the cmd process that was running on my system during system-wide collection.  Therefore, I type the following:

CVCollectionCmd.exe /Analyze “c:/users/MyName/SystemWideCollection_2011_11_14_141211.CVTrace” /process cmd

I also collected a non-system-wide trace associated with this process.  To analyze this trace, I do not need to specify the process of interest.  Thus, I need only specify the location of the CVTrace file:

CVCollectionCmd.exe /Analyze "C:\Users\MyName\cmd_2011-11-14_131049.CvTrace"

Once analyzed, you can open the trace in Visual Studio 11 to view the results.

See also: The MSDN documentation for CVCollectionCmd.  It describes the full list of commands.

James Rapp – Parallel Computing Platform

The Application

To best illustrate the concepts in this entry, I’ll use a fictional weather simulation app.  It simulates changes in weather using multiple iterations (each iteration represents an hour of simulation time).  For each iteration, the app performs the following four-step calculation:

1. Update solar input
2. Calculate ground temperature
3. Update atmospheric pressure
4. Calculate precipitation

This simulation can be performed in parallel.  In this application, I use C# and the .NET Thread Pool to parallelize the workload. 

Without diving into the implementation of the simulation functions themselves, the code does this:

static void Main(string[] args)
{
   DateTime simTime=new DateTime(2011, 11, 5, 0, 0, 0);
   doneEvents = new ManualResetEvent[degreeOfParallelism];
   for (int i = 0; i < doneEvents.Length; i++)
   {
      doneEvents[i] = new ManualResetEvent(false);
   }
         
   //each iteration represents one hour of weather activity
   for (int n = 0; n < numIterations; n++)
   {
      //Phase 1 - Update solar input
      for (int i = 0; i < degreeOfParallelism; i++)
      {
         doneEvents[i].Reset();
         ThreadPool.QueueUserWorkItem(updateSolarInput, i);
      }
      WaitHandle.WaitAll(doneEvents);
      //Phase 2 - Calculate ground temperature
      for (int i = 0; i < degreeOfParallelism; i++)
      {
         doneEvents[i].Reset();
         ThreadPool.QueueUserWorkItem(calculateGroundTemperature, i);
      }
      WaitHandle.WaitAll(doneEvents);
      //Phase 3 - Update atmospheric pressure
      for (int i = 0; i < degreeOfParallelism; i++)
      {
         doneEvents[i].Reset();
         ThreadPool.QueueUserWorkItem(updateAtmosphericPressure, i);
      }
      WaitHandle.WaitAll(doneEvents);
      //Phase 4 - Calculate precipitation
      for (int i = 0; i < degreeOfParallelism; i++)
      {
         doneEvents[i].Reset();
         ThreadPool.QueueUserWorkItem(calculatePrecipitation, i);
      }
      WaitHandle.WaitAll(doneEvents);
      simTime=simTime.AddHours(1);
   }
}

A static variable, degreeOfParallelism, defines the number of threads that simultaneously participate in the weather simulation.  Since the results of each phase in an iteration depend on the previous phase, I use ManulResetEvents to effectively create a barrier, so threads don’t proceed to the next phase until all threads have finished the current phase.

In this example, I am running this on a machine with a dual core processor.  I set degreeOfParallelism to 2 and ran the code for 2 iterations.  I want to run this under the Concurrency Visualizer to get a general picture of the way this executes.  I’m curious to know whether the phases are load balanced and roughly how long each phase takes.  Here is a picture of the Threads View after running this under the Concurrency Visualizer:

From this view, I can see that the the Main thread simply queued the work items and blocked while the computation progressed.  The three worker threads carried out the work (as shown by the green execution category).  The worker threads aren’t 100% busy however.  From this picture, it’s hard to know when each phase was carried out.  As introduced in the previous entry, I can use a span to demarcate the execution of an application phase.  But unlike the example shown in the previous entry, I want to use my own Marker provider, rather than use the default provider.

Creating Your Own Marker Provider

The expected convention is to use a single provider per application.  I definitely want to use my own provider in order to avoid conflicts with other applications or libraries that already make use of the default Marker provider.

To create the provider in C#, I instantiate a new MarkerWriter object by specifying a GUID:

MarkerWriter writer = new MarkerWriter(
      new Guid("9f34bddd-eae4-40c9-b668-91d78fc0b316"));

I can’t generate Marker events from the provider itself.  Instead, I need to generate events from a MarkerSeries object.  I’ll describe this further later in the entry.  For now, think of a MarkerSeries as a serial channel of Marker events from a MarkerWriter.  A MarkerWriter may have multiple MarkerSeries.  I create my MarkerSeries using the following constructor:

MarkerSeries series = writer.CreateMarkerSeries("");

The constructor takes a string, meant as a friendly name of the series.  At the moment, I’m only planning to use one series for this provider, so I’ll leave the name empty.

I am now ready to begin generating events from series.  In order for the Concurrency Visualizer to listen to these events and display them in the Threads View, I need to register my new provider.  To do so, I open the Advanced Settings Dialog (Analyze->Concurrency Visualizer->Advanced Settings).  Next, I select the Markers tab.  Here, I select the “Add new provider” button:

I type the friendly name of my provider (“WeatherApp”) and specify its GUID (the same one I used when instantiating the MarkerWriter). 

Generating Spans and Flags

My first step is to surround each phase of my application with a Marker span.  This way, I can see when each phase occurs on each thread.  For example, on either side of calculating the ground temperature, I add the following calls:

var span = series.EnterSpan("Calculating Ground Temperature");
//code that calculates ground temperature
span.Leave();

In addition, I want to indicate the simulation time when I begin each iteration.  I’ll add a flag whenever I begin a new iteration.

...
//each iteration represents one hour of weather activity
for (int n = 0; n < numIterations; n++)
{
        series.WriteFlag("Iteration " + n + 
           ": time = " + simTime.TimeOfDay);
        //Phase 1 - Update solar input
        ...

Using my series object, I generate a flag specifying the iteration number and the corresponding simulation time.  Simulation time is tracked in the simTime structure (DateTime).

As a result of adding these calls, I now see the following visualization in the Threads View:

I can see that the Main Thread generated two flags, which show the start of two iterations.  Each worker thread generated spans when it entered and left each phase within an iteration.  For example, I can see that Worker Thread 3400 executed all four phases within the first iteration but only two of the phases in the second iteration.  Some of the text is cut off because there isn’t enough room to display it.  I can hover over each span or zoom in to see its full description. 

By adding these flags and spans, I can already understand a lot more about the way this application executes.  As one example, I can see that the first phase in an iteration seems to take twice as long on one of the threads as compared to the other.  This is clearly one area ripe for investigation.

Using Categories

In some cases, you may find it useful to differentiate various application events by groups.  This is very specific to the set of events generated by each application.  In this example, it makes sense for me to divide events into three categories:

1. Events that describe the overall behavior of the weather simulation, such as an iteration beginning.
2. Events related to calculations pertaining to the ground (i.e. solar absorption and ground temperature calculations).
3. Events that relate to the atmosphere (i.e. calculating the atmospheric pressure and precipitation).

Therefore, I will group flags that mark the beginning of an iteration into category 0, spans that demarcate the updateSolarInput and calculateGroundTemperature phases into category 1, and spans that demarcate the updateAtmosphericPressure and calculatePrecipitation into category 2.

To specify the category for the flags I generate, I call a different overload of WriteFlag():

series.WriteFlag(0, "Iteration " + n + 
      ": time = " + simTime.TimeOfDay);

In addition to the description, I now pass an integer that specifies that the flag belongs to category 0.

Similarly, to specify the category associated with the spans I generate, I make the following call:

var span = series.EnterSpan(1, "Calculating Ground Temperature");
//code that calculates ground temperature
span.Leave();

Since this span demarcates a region of code responsible for ground calculations, I group it with category 1.  After making these changes, I run my code again under the Concurrency Visualizer and see the following picture:

Since I grouped my Markers into various categories, the Concurrency Visualizer displays them in different colors for the purpose of glancibility.

Using Importance Levels

Marker events aren’t all created equal.  You may want to call a greater importance to certain events.  I can use the Importance enum, which defines low, normal, high, and critical importance levels.  For the purposes of illustration, suppose I consider the 0th iteration of this simulation to be incredibly unimportant while the 1st iteration is critically important.  I can represent this in the flags I am generating for each iteration by adding Importance as a parameter when I write the flag.  For the 0th iteration, I generate a flag with low importance:

series.WriteFlag(Importance.Low, 0, "Iteration " + 
     n + ": time = " + simTime.TimeOfDay);
And for the 1st iteration, I generate a flag with critical importance:

series.WriteFlag(Importance.Critical, 0, "Iteration " + n + 
     ": time = " + simTime.TimeOfDay);

In this case, I’ll also consider the spans I generate for the calculateGroundTemperature phase to have high importance:

var span = series.EnterSpan(Importance.High, 1, 
   "Calculating Ground Temperature");

If an instantaneous event occurs that is severe enough, such as an exception being thrown, I may want to call special attention to it in my application.  To do this, I can generate an alert.  An alert is a special case of a flag, whose importance is critical.  An alert’s category is the reserved –1 category.  In my application, I added the following call to the code that throws an exception:

series.WriteAlert(e.Message);

e is the exception and the above alert simply wraps the exception’s message.  After the above changes, I now see the following picture:

The difference in this picture is the changed appearance of the flags that mark the beginning of an iteration.  The flag that marks the 0th iteration is now smaller while the other flag is larger and shows a ‘!’ (to indicate that it is critical).  In addition, I can see a red flag that represents an alert generated by thread 3428 while it was calculating precipitation.  When I hover over it, the tooltip shows the message of the exception I wrapped in the alert.

Using categories and importance levels is not only useful in affecting the appearance of Markers.  These can also be used as parameters for filtering.

Filtering

In some cases, you may not care to see unimportant Markers or Markers from a specific category.  In fact, you may not want to see Markers from a particular provider at all.  You can filter based on these characteristics in the Advanced Settings dialog.  In this case, I only want to collect Markers from categories 0 and 1.  Recall that this includes the flags that mark the beginning of iterations and spans that relate to ground calculations.  In addition, I only want to collect events with importance of high or critical.  I can configure this for my “WeatherApp” provider by selecting it and then clicking the “Edit provider” button:

I specify that I want to collect categories 0 and 1 by entering “0,1” in the categories field.  If I wanted to collect a larger range of categories, such as 100 to 200, I could enter “100-200”.  I specify that I only want to collect events with at least high importance by using the optional dropdown. 

As an aside, I can choose not to collect events from a particular provider altogether by unchecking the box next to its name in the list of providers.

After changing these options, I now see the following picture:

Based on the options I selected, I now only see Markers with importance of high or critical and belonging to category 0 or 1.  This includes the flag marking the beginning of iteration 1 and the spans marking the phase that calculates ground temperature.

Using Series

As I alluded to earlier in this entry, a Series is a logical grouping of events that are generated by a particular provider.  If you need to break the events you are generating into different logical serial channels of events, you can use different Series under a single provider.  This is especially meaningful and important when different series of events are independent of one another.

In my weather simulation, I showed the use of categories by breaking overall simulation events, ground events, and atmosphere events into distinct categories.  To illustrate series, I’ll now remove the category distinctions, and instead generate these categories of events from different series.  First, I need to create three different series:

overallSeries = writer.CreateMarkerSeries("Simulation");
groundSeries = writer.CreateMarkerSeries("Ground");
atmosphereSeries = writer.CreateMarkerSeries("Atmosphere");

I give each series a descriptive name to help me remember the set of events generated by each.  I’ll use the “Simulation” series to generate events that describe the simulation overall.  This includes the events that mark the beginning of each iteration.  I’ll use the “Ground” series for events related to ground calculations.  This includes the spans that demarcate the updateSolarInput and calculateGroundTemperature phases.  The “Atmosphere” series generates events pertaining to atmospheric calculations, namely, the updateAtmosphericPressure and calculatePrecipitation phases.  After updating my code, I see the following picture when I run it under the Concurrency Visualizer:

I can now see that the description associated with each Marker channel shows the provider and the series.  The top channel shows the events from the “Simulation” series, the next three show events from the “Atmosphere” series, and the next two show events from the “Ground” series.  Markers from different series are shown in different channels in the Threads View.  In particular, there is a unique Marker channel for each unique combination of thread ID, provider, and series.

Conclusion

As you can see from the previous entry, the basic features of the Concurrency Visualizer SDK are very simple to use.  However, sometimes the basic usage scenarios just aren’t adequate when it comes to visualizing more complex patterns of application behavior.  The Concurrency Visualizer SDK exposes more control over visualization for those who need it, but makes it easy to get started for those who don’t.  Whether you need this type of control or not, I hope this entry at least gives you the tools to get started should you choose to.  Whether used at a basic level or advanced level, the Concurrency Visualizer SDK can greatly decrease the time it takes to make sense of complex diagnostic data.

James Rapp – Parallel Computing Platform

The Concurrency Visualizer displays rich data related to CPU thread behavior, DirectX activity, and disk I/O, among other things.  This information can be incredibly valuable when investigating application behavior, but sometimes it's difficult to quickly understand how the data displayed in the Concurrency Visualizer maps to application behavior.  For this reason, we've added the Concurrency Visualizer SDK, which you can use in Visual Studio 11 Developer Preview.  This SDK allows you to instrument your code in order to augment the visualizations displayed in the Threads View of the Concurrency Visualizer.  These visualizations, referred to as "Markers", make the Threads View data more semantically meaningful because they represent specific phases and events in your application.

For those of you who have used Scenario Markers with the Visual Studio 2010 Concurrency Visualizer, you'll find that the Concurrency Visualizer SDK is conceptually similar, but provides much more control and flexibility.

The SDK exposes three visual primitives:

1. Span
2. Flag
3. Message

A span represents an interval of time in your application, such as an application phase.  A flag represents a single point in time (e.g. the point where some value reached a threshold or when an exception was thrown).  A message also represents a single point in time, but is meant as a visual analog to classic event-style tracing.  So what might have previously been dumped to a log file can now be wrapped in a message call.  This will yield visualizations in the Threads View and you'll have the ability (via the UI) to export the data into a CSV file.  While there are more advanced ways to make use of this SDK, I'll try to introduce the most basic usage scenarios in this entry.

Adding the SDK to your Project

To get started, you need to add the SDK to your project:

In the dialog that appears, select the project in which you want to use the SDK and then click “Add SDK to Selected Project”.  For a managed project, this adds a reference to the DLL associated with the SDK.  For native projects, this adds the SDK header file to the project’s include directories.  Next, reference the namespace associated with the SDK in your source code.  In C#, add the following using statement:

using Microsoft.ConcurrencyVisualizer.Instrumentation;

In C++, include the header file:

#include "cvmarkersobj.h"

This is a header with C++ style conventions.  If you’re using C (or C++, but want to use the C-style conventions anyway) , include this header file instead:

#include "cvmarkers.h"

This header exposes the same functionality, but follows C-style conventions.

Basic Span Usage

A span is meant to represent an application phase.  Consider the following example code in C#:

        static void Main(string[] args)

        {

            phase1();

            phase2();

        } 

Both phases perform some unknown amount of work.  When I profile this application and view the results in the Threads View, I get the following:

I can see that the main thread executed both phases, but I have no idea which is which.  I may be able to deduce this by clicking each green segment and looking at the call stacks in an attempt to determine where one phase ends and the next beings, but this is not guaranteed to work.  Therefore, I can instrument these with spans.  In C# there are two syntactical ways to do this, I’ll demonstrate the first approach on the first phase and the second approach on the second phase:

        static void Main(string[] args)

        {

            using (Markers.EnterSpan("Phase 1"))

            {

                phase1();

            }

            var span = Markers.EnterSpan("Phase 2");

            phase2();

            span.Leave();

        }

Both phases are now demarcated using a span, each using a different syntax.  The choice of syntax is simply a matter of personal preference.  Either way, I now get the following visualization in the Threads View:

Note that in C++, I’d make the following call for a span:

marker_series series;

//some code

{

   span s(series, _T("Phase 1"));

   //some code

}

I can now see that a new channel is visible in the timeline.  This Marker channel displays the two spans I added to my code: Phase 1 and Phase 2.  These mark the points where each phase begun and ended.  It is now crystal clear exactly which stage of execution in the main thread corresponds to each phase.  I can see that the second phase takes roughly twice as long as the first.  In fact, I can select each span to see the exact duration in the report below.  It turns out that phase 1 took 429.8 ms while phase 2 took 724.2 ms.  Note that the thread ID associated with this Marker channel is the ID of the main thread.  You can see this thread ID next to the name of the Marker channel.  This indicates that the Marker events were generated from the main thread (which makes sense when you look at the source code).  If these events had been generated from a different thread, the Marker channel would be associated with a different thread ID and by default, the channel would appear under the thread that generated its events.

Basic Flag Usage

You may want demarcate a specific event in your application that doesn’t have a duration, but rather occurs at a single point in time.  One example of this is the point at which an exception is thrown.  Another example could be a stock market app that wants to call attention to the value of a particular stock reaching a threshold.  To accomplish this, use a flag.  Using the same code from the span example, suppose I want to indicate when phase 1 completes.  I simply need to add a flag after the call to phase1(), but before the call to phase2():

        static void Main(string[] args)

        {

            phase1();

            Markers.WriteFlag("Phase 1 complete");

            phase2();

        }

This results in the following Visualization:

To generate a flag in C++, I’d write the following:

marker_series series;

series.write_flag(_T("Phase 1 complete"));

The Marker channel now contains an icon, whose bottom tip represents the exact point in time that the call to WriteFlag() was executed.  This demarcates the point when phase1() was complete, but phase2() hadn’t yet begun.

Basic Message Usage

In many applications, you’ll want to output data to a log file because it may come in handy later when diagnosing performance or when debugging.  Most of the time, you won’t look at a log file, and even if you do, you’ll likely look for specific information in it, ignoring 90% of it.  For this type of information, you can use a message.  Suppose I have the following code, which writes files and measures the amount of time required to output each file:

        static void Main(string[] args)

        {

            getFileNames();

            Stopwatch sw = new Stopwatch();

            foreach (String fileName in fileNames)

            {

                sw.Restart();

                writeFile(fileName);

                sw.Stop();

                long duration = sw.ElapsedMilliseconds;

            }

        }

If I want to log the amount of time required to write each file using a message, I simply add the following code:

        static void Main(string[] args)

        {

            getFileNames();

            Stopwatch sw = new Stopwatch();

            foreach (String fileName in fileNames)

            {

                sw.Restart();

                writeFile(fileName);

                sw.Stop();

                long duration = sw.ElapsedMilliseconds;

                Markers.WriteMessage(fileName + ":" + duration);

            }

        }

In the Threads View, I see the following:

To generate a message in C++, I’d write the following:

marker_series series;

series.write_message(_T("My Message"));

Each little grey rectangle represents a message.  It is visually nonintrusive because after all, log-style output will be ignored most of the time.  If I want to see the output for a message, I can hover over it and see the tooltip.  In addition, I can view the Markers report by selecting “Markers” in the Visible Timeline Profile:

This report lists all of the Markers in the current visible time range (thus, zooming/panning filters this report).  In this case, the only Markers were the 10 messages I generated.  For each message, I can see the time at which it occurred and its associated text (in the Details column), among other things.  In this case, I look at the output I generated (in the Details column) and find that all of the files took roughly the same amount of time to write, ranging from 445 ms to 449 ms.  I can export this table as a CSV by clicking the “Export…” button above this tabular report (not visible in this screenshot because I clipped it).

Conclusion

What I discussed in this entry was the most basic way to get started with the Concurrency Visualizer SDK on made up code examples.  There are more sophisticated ways to use this SDK, including using categories and importance levels, and generating Markers from multiple providers and series.  You can even visualize ETW events that follow the event source convention as Markers.  However, I’ll leave this to future entries, in the interest of brevity.

James Rapp - Parallel Computing Platform

Aren't you all excited about it? Don't you want to try your hand at it?

Now it is the time with Visual Studio 11 Ultimate Developer Preview on Windows Developer Preview. You can write, build and debug your C++ AMP applications in a single IDE effortlessly. To get you started, check out this article on MSDN that walks you through how to debug a C++ AMP application.