Introduction to OpenMP Data Structure: kmp_base_info

In order to understand how OpenMP works internally, in addition to the essential part of functions, we also need to learn some basic data structures. This series of posts are going to give you a basic impression on some OpenMP essential data structures in runtime library. Let’s get started from the most basic and also one of the most complicated one: kmp_base_info.

typedef struct kmp_base_info {
  kmp_desc_t th_info;
  kmp_team_p *th_team; /* team we belong to */
  kmp_root_p *th_root; /* pointer to root of task hierarchy */
  kmp_info_p *th_next_pool; /* next available thread in the pool */
  kmp_disp_t *th_dispatch; /* thread's dispatch data */
  int th_in_pool; /* in thread pool (32 bits for TCR/TCW) */

  int th_team_nproc; /* number of threads in a team */
  kmp_info_p *th_team_master; /* the team's master thread */
  int th_team_serialized; /* team is serialized */
  microtask_t th_teams_microtask; /* save entry address for teams construct */
  int th_teams_level; /* save initial level of teams construct */

  kmp_uint64 th_team_bt_intervals;
  omp_allocator_handle_t th_def_allocator; /* default allocator */
  /* The data set by the master at reinit, then R/W by the worker */
  int th_set_nproc; /* if > 0, then only use this request for the next fork */
  kmp_hot_team_ptr_t *th_hot_teams; /* array of hot teams */
      th_set_proc_bind; /* if != proc_bind_default, use request for next fork */
      th_teams_size; /* number of teams/threads in teams construct */
  int th_prev_level; /* previous level for affinity format */
  int th_prev_num_threads; /* previous num_threads for affinity format */
  kmp_local_t th_local;
  struct private_common *th_pri_head;

  kmp_team_p *th_serial_team; /*serialized team held in reserve*/
  /* The following are also read by the master during reinit */
  struct common_table *th_pri_common;
  volatile kmp_uint32 th_spin_here; /* thread-local location for spinning */
  /* while awaiting queuing lock acquire */
  volatile void *th_sleep_loc; // this points at a kmp_flag
  ident_t *th_ident;
  unsigned th_x; // Random number generator data
  unsigned th_a; // Random number generator data

  /* Tasking-related data for the thread */
  kmp_task_team_t *th_task_team; // Task team struct
  kmp_taskdata_t *th_current_task; // Innermost Task being executed
  kmp_uint8 th_task_state; // alternating 0/1 for task team identification
  kmp_uint8 *th_task_state_memo_stack; // Stack holding memos of th_task_state
  // at nested levels
  kmp_uint32 th_task_state_top; // Top element of th_task_state_memo_stack
  kmp_uint32 th_task_state_stack_sz; // Size of th_task_state_memo_stack
  kmp_uint32 th_reap_state; // Non-zero indicates thread is not
  // tasking, thus safe to reap

  /* More stuff for keeping track of active/sleeping threads (this part is
     written by the worker thread) */
  kmp_uint8 th_active_in_pool; // included in count of #active threads in pool
  int th_active; // ! sleeping; 32 bits for TCR/TCW
  struct cons_header *th_cons; // used for consistency check

  /* Add the syncronizing data which is cache aligned and padded. */
  kmp_balign_t th_bar[bs_last_barrier];

  volatile kmp_int32
      th_next_waiting; /* gtid+1 of next thread on lock wait queue, 0 if none */
  kmp_cond_align_t th_suspend_cv;
  kmp_mutex_align_t th_suspend_mx;
  std::atomic th_suspend_init_count;
  std::atomic th_blocking;
  kmp_cg_root_t *th_cg_roots; // list of cg_roots associated with this thread
} kmp_base_info_t;

In order to make it more understandable, I’ve removed some unimportant fields controlled by macros, like OMPT. I also remove OS dependent part, only focusing on Linux. However, they just have different types on different OS. It does not affect the essential concept.

(To be continued…)

Internal OpenMP: How parallel directive works

Let’s start with parallel directive, which is maybe the most widely used directive in OpenMP. In this post, I’ll use the following basic example to demonstrate how OpenMP library internals works.

void func() {
  int i = 0, j = 1;
#pragma omp parallel

After compilation, it is transformed to following code snippet by compiler (well, different compiler may generate code with a little different style but essentially they are same):

void omp_outlined(int gtid, int btid, int *a, int *b) {
void func() {
  int i = 0, j = 1;
  ident_t loc;
  // some operation on loc
  // ...
  __kmpc_fork_call(loc, 2, omp_outlined, &i, &j);

Since our focus is not on front end so we just briefly introduce what is done by compiler. The compiler will take all statements in the parallel region and outline them into a new function, omp_outlined in this case. This function is actually of type void(int, int, ...) where the first argument is global thread id, and the second one is bound thread id. We’ll introduce them later. The rest of arguments are actually variadic standing for all variables captured by the parallel region. In the example above, the integers i and j are used in the parallel region so they’re captured. In the outlined function, the statements are pretty simple which is just to operate the two variables using each pointer. What’s more, the compiler also creates a new variable of type ident_t describing a source location. It is mainly for debug. After that, a function call to __kmpc_fork_call is generated, and that’s almost it.

Although the example above is pretty simple, it actually shows the essence of how OpenMP compiler deals with OpenMP directive, that is, outlines parallel regions into dedicated functions, and then emits function calls correspondingly. It is actually pretty good for feature developments because it hides all details into the runtime function in case of breaking compilation. However, it also prevents classic compiler optimizations like constant propagation, etc. We’ll not detail them here but we will come back to this topic in another series about how OpenMP compiler works.

Alright, back to our topic.

(To be continued…)

Internal OpenMP: Understand How OpenMP Works Step by Step

If you have seen the page "About Me", you will know my research interest is LLVM and OpenMP. Basically, the main part is to optimize OpenMP to improve its performance, well, more about offloading to GPU. The reason that LLVM is also mentioned is that my vision is to introduce more information into runtime library so that more optimization can be performed during runtime which requires some works in compiler. I’ve been working on OpenMP for about half a year. There’re plenty of awesome tutorials and books to show you how to write OpenMP correctly and efficiently, but there are seldom articles to tell you how OpenMP works underneath. From my perspective, it is not very friendly to friends who want to contribute to OpenMP. In order to help me understand things better, I’d like to write a series of blogs about how OpenMP works internally.

Honestly, I’m still a newbie so the organization of this series may not be the best way. Plus, some statements may not be correct. So I sincerely welcome any comment. I’ll start with what I’m working on that is related to parallel region, task and so forth. Later as I understand the whole structure more deeply, I’ll update previous posts correspondingly if anything is wrong or partial.

OpenMP Learning Notes

  1. In C/C++, OpenMP directives are specified by using the #pragma mechanism provided by the C and C++ standards.
  2. OpenMP directives for C/C++ are specified with #pragma directives. The syntax of an OpenMP directive is as follows:
    #pragma omp directive-name [clause[ [,] clause] ... ] new-line
    Each directive starts with #pragma omp. The remainder of the directive follows the conventions of the C and C++ standards for compiler directives. In particular, white space can be used before and after the #, and sometimes white space must be used to separate the words in a directive. Some OpenMP directives may be composed of consecutive #pragma directives if specified in their syntax.
  3. Preprocessing tokens following #pragma omp are subject to macro replacement.
  4. Directives are case-sensitive. Each of the expressions used in the OpenMP syntax inside of the clauses must be a valid assignment-expression of the base language unless otherwise specified.
  5. Directives may not appear in constexpr functions or in constant expressions. Variadic parameter packs cannot be expanded into a directive or its clauses except as part of an expression argument to be evaluated by the base language, such as into a function call inside an if clause.
  6. Only one directive-name can be specified per directive (note that this includes combined directives). The order in which clauses appear on directives is not significant. Clauses on directives may be repeated as needed, subject to the restrictions listed in the description of each clause.
  7. Some clauses accept a list, an extended-list, or a locator-list.
    • A list consists of a comma-separated collection of one or more list items. A list item is a variable or an array section.
    • An extended-list consists of a comma-separated collection of one or more extended list items. An extended list item is a list item or a function name.
    • A locator-list consists of a comma-separated collection of one or more locator list items. A locator list item is any lvalue expression, including variables, or an array section.
  8. Some executable directives include a structured block. A structured block:
    • may contain infinite loops where the point of exit is never reached;
    • may halt due to an IEEE exception;
    • may contain calls to exit(), _Exit(), quick_exit(), abort() or functions with a _Noreturn specifier (in C) or a noreturn attribute (in C/C++);
    • may be an expression statement, iteration statement, selection statement, or try block, provided that the corresponding compound statement obtained by enclosing it in { and } would be a structured block.
  9. Stand-alone directives do not have any associated executable user code. Instead, they represent executable statements that typically do not have succinct equivalent statements in the base language. There are some restrictions on the placement of a stand-alone directive within a program. A stand-alone directive may be placed only at a point where a base language executable statement is allowed. A stand-alone directive may not be used in place of the statement following an if, while, do, switch, or label.
  10. In implementations that support a preprocessor, the _OPENMP macro name is defined to have the decimal value yyyymm where yyyy and mm are the year and month designations of the version of the OpenMP API that the implementation supports. If a #define or a #undef preprocessing directive in user code defines or undefines the _OPENMP macro name, the behavior is unspecified.