Replace Annotations with Intel® oneAPI Threading Building Blocks...

Intel® Advisor User Guide

Download PDF

ID 766448

Date 3/22/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-659E6DF4-D35A-4697-9742-B19A3B1DF1FE

View Details

Replace Annotations with Intel® oneAPI Threading Building Blocks (oneTBB) Code

This topic explains the steps needed to implement parallelism proposed by the Intel Advisor annotations by adding Intel® oneAPI Threading Building Blocks (oneTBB) parallel framework code.

Add oneTBB code to add appropriate synchronization of shared resources, using the LOCK annotations as a guide. The following topics cover the oneTBB synchronization options:
- Intel® oneAPI Threading Building Blocks (oneTBB) Mutexes
- Intel® oneAPI Threading Building Blocks (oneTBB) Mutex - Example
Add code to create oneTBB tasks, using the SITE/TASK annotations as a guide. The following topics cover the oneTBB task creation options:
- Parallelize Functions - Intel® oneAPI Threading Building Blocks (oneTBB) Tasks
- Parallelize Data - Intel® oneAPI Threading Building Blocks (oneTBB) Counted Loops
- Parallelize Data - Intel® oneAPI Threading Building Blocks (oneTBB) Loops with Complex Iteration Control

This is the recommended order of tasks for replacing the annotations with oneTBB code:

Add appropriate synchronization of shared resources, using LOCK annotations as a guide.
Test to verify you did not break anything, before adding the possibility of non-deterministic behavior with parallel tasks.
Add code to create oneTBB tasks or loops, using the SITE/TASK annotations as a guide.
Test with one thread, to verify that your program still works correctly.
Test with more than one thread to see that the multithreading works as expected.

The oneTBB parallel framework creates worker threads automatically. In general, you should concern yourself only with the tasks, and leave it to the framework to create and destroy the worker threads.

If you do need some control over creation and destruction of worker threads, read about task_scheduler_init in the oneTBB Reference manual.

The table below shows the serial, annotated program code in the left column and the equivalent oneTBB parallel code in the right column for some typical code to which parallelism can be applied.

Serial Code with Intel Advisor Annotations	Parallel Code using oneTBB
// Locking ANNOTATE_LOCK_ACQUIRE(); Body(); ANNOTATE_LOCK_RELEASE():	// Locking can use various mutex types provided // by oneTBB. For example: #include <tbb/tbb.h> ... tbb::mutex g_Mutex; ... { tbb::mutex::scoped_lock lock(g_Mutex); Body(); }
// Do-All Counted loops, one task ANNOTATE_SITE_BEGIN(site); For (I = 0; I < N; ++) { ANNOTATE_ITERATION_TASK(task); {statement;} } ANNOTATE_SITE_END();	// Do-All Counted loops, using lambda // expressions #include <tbb/tbb.h> ... tbb::parallel_for(0,N,[&](int I) { statement; });
// Create Multiple Tasks ANNOTATE_SITE_BEGIN(site); ANNOTATE_TASK_BEGIN(task1); statement-or-task1; ANNOTATE_TASK_END(); ANNOTATE_TASK_BEGIN(task2); statement-or-task2; ANNOTATE_TASK_END(); ANNOTATE_SITE_END();	// Create Multiple tasks, using lambda // expressions #include <tbb/tbb.h> ... tbb::parallel_invoke( [&]{statement-or-task1;}, [&]{statement-or-task2;} );

Serial Code with Intel Advisor Annotations

Parallel Code using oneTBB

// Locking
ANNOTATE_LOCK_ACQUIRE();
  Body();
ANNOTATE_LOCK_RELEASE():

// Locking can use various mutex types provided 
// by oneTBB. For example:
#include <tbb/tbb.h>
 ...
 tbb::mutex g_Mutex;
 ...
{
    tbb::mutex::scoped_lock lock(g_Mutex);
    Body();
}

// Do-All Counted loops, one task
ANNOTATE_SITE_BEGIN(site);
  For (I = 0; I < N; ++) {
    ANNOTATE_ITERATION_TASK(task);
      {statement;}
  }
ANNOTATE_SITE_END();

// Do-All Counted loops, using lambda 
// expressions
#include <tbb/tbb.h>
  ...
  tbb::parallel_for(0,N,[&](int I) { 
    statement;
  });

// Create Multiple Tasks
ANNOTATE_SITE_BEGIN(site);
  ANNOTATE_TASK_BEGIN(task1);
    statement-or-task1;
  ANNOTATE_TASK_END();
  ANNOTATE_TASK_BEGIN(task2);
    statement-or-task2;
  ANNOTATE_TASK_END();
ANNOTATE_SITE_END();

// Create Multiple tasks, using lambda 
// expressions
#include <tbb/tbb.h>

  ...
  tbb::parallel_invoke(
    [&]{statement-or-task1;},
    [&]{statement-or-task2;}
  );

For information about common parallel programming patterns and how to implement them in oneTBB, see the oneTBB help topic Design Patterns.

Parent topic: Add Parallelism to Your Program

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Advisor User Guide

Replace Annotations with Intel® oneAPI Threading Building Blocks (oneTBB) Code