libgomp/libgomp.h

   1 /* Copyright (C) 2005, 2007, 2008 Free Software Foundation, Inc.
   2    Contributed by Richard Henderson <rth@redhat.com>.
   3
   4    This file is part of the GNU OpenMP Library (libgomp).
   5
   6    Libgomp is free software; you can redistribute it and/or modify it
   7    under the terms of the GNU Lesser General Public License as published by
   8    the Free Software Foundation; either version 2.1 of the License, or
   9    (at your option) any later version.
  10
  11    Libgomp is distributed in the hope that it will be useful, but WITHOUT ANY
  12    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13    FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  14    more details.
  15
  16    You should have received a copy of the GNU Lesser General Public License
  17    along with libgomp; see the file COPYING.LIB.  If not, write to the
  18    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19    MA 02110-1301, USA.  */
  20
  21 /* As a special exception, if you link this library with other files, some
  22    of which are compiled with GCC, to produce an executable, this library
  23    does not by itself cause the resulting executable to be covered by the
  24    GNU General Public License.  This exception does not however invalidate
  25    any other reasons why the executable file might be covered by the GNU
  26    General Public License.  */
  27
  28 /* This file contains data types and function declarations that are not
  29    part of the official OpenMP user interface.  There are declarations
  30    in here that are part of the GNU OpenMP ABI, in that the compiler is
  31    required to know about them and use them.
  32
  33    The convention is that the all caps prefix "GOMP" is used group items
  34    that are part of the external ABI, and the lower case prefix "gomp"
  35    is used group items that are completely private to the library.  */
  36
  37 #ifndef LIBGOMP_H
  38 #define LIBGOMP_H 1
  39
  40 #include "config.h"
  41 #include "gstdint.h"
  42
  43 #include <pthread.h>
  44 #include <stdbool.h>
  45
  46 #ifdef HAVE_ATTRIBUTE_VISIBILITY
  47 # pragma GCC visibility push(hidden)
  48 #endif
  49
  50 #include "sem.h"
  51 #include "mutex.h"
  52 #include "bar.h"
  53 #include "ptrlock.h"
  54
  55
  56 /* This structure contains the data to control one work-sharing construct,
  57    either a LOOP (FOR/DO) or a SECTIONS.  */
  58
  59 enum gomp_schedule_type
  60 {
  61   GFS_RUNTIME,
  62   GFS_STATIC,
  63   GFS_DYNAMIC,
  64   GFS_GUIDED,
  65   GFS_AUTO
  66 };
  67
  68 struct gomp_work_share
  69 {
  70   /* This member records the SCHEDULE clause to be used for this construct.
  71      The user specification of "runtime" will already have been resolved.
  72      If this is a SECTIONS construct, this value will always be DYNAMIC.  */
  73   enum gomp_schedule_type sched;
  74
  75   int mode;
  76
  77   union {
  78     struct {
  79       /* This is the chunk_size argument to the SCHEDULE clause.  */
  80       long chunk_size;
  81
  82       /* This is the iteration end point.  If this is a SECTIONS construct,
  83          this is the number of contained sections.  */
  84       long end;
  85
  86       /* This is the iteration step.  If this is a SECTIONS construct, this
  87          is always 1.  */
  88       long incr;
  89     };
  90
  91     struct {
  92       /* The same as above, but for the unsigned long long loop variants.  */
  93       unsigned long long chunk_size_ull;
  94       unsigned long long end_ull;
  95       unsigned long long incr_ull;
  96     };
  97   };
  98
  99   /* This is a circular queue that details which threads will be allowed
 100      into the ordered region and in which order.  When a thread allocates
 101      iterations on which it is going to work, it also registers itself at
 102      the end of the array.  When a thread reaches the ordered region, it
 103      checks to see if it is the one at the head of the queue.  If not, it
 104      blocks on its RELEASE semaphore.  */
 105   unsigned *ordered_team_ids;
 106
 107   /* This is the number of threads that have registered themselves in
 108      the circular queue ordered_team_ids.  */
 109   unsigned ordered_num_used;
 110
 111   /* This is the team_id of the currently acknowledged owner of the ordered
 112      section, or -1u if the ordered section has not been acknowledged by
 113      any thread.  This is distinguished from the thread that is *allowed*
 114      to take the section next.  */
 115   unsigned ordered_owner;
 116
 117   /* This is the index into the circular queue ordered_team_ids of the
 118      current thread that's allowed into the ordered reason.  */
 119   unsigned ordered_cur;
 120
 121   /* This is a chain of allocated gomp_work_share blocks, valid only
 122      in the first gomp_work_share struct in the block.  */
 123   struct gomp_work_share *next_alloc;
 124
 125   /* The above fields are written once during workshare initialization,
 126      or related to ordered worksharing.  Make sure the following fields
 127      are in a different cache line.  */
 128
 129   /* This lock protects the update of the following members.  */
 130   gomp_mutex_t lock __attribute__((aligned (64)));
 131
 132   /* This is the count of the number of threads that have exited the work
 133      share construct.  If the construct was marked nowait, they have moved on
 134      to other work; otherwise they're blocked on a barrier.  The last member
 135      of the team to exit the work share construct must deallocate it.  */
 136   unsigned threads_completed;
 137
 138   union {
 139     /* This is the next iteration value to be allocated.  In the case of
 140        GFS_STATIC loops, this the iteration start point and never changes.  */
 141     long next;
 142
 143     /* The same, but with unsigned long long type.  */
 144     unsigned long long next_ull;
 145
 146     /* This is the returned data structure for SINGLE COPYPRIVATE.  */
 147     void *copyprivate;
 148   };
 149
 150   union {
 151     /* Link to gomp_work_share struct for next work sharing construct
 152        encountered after this one.  */
 153     gomp_ptrlock_t next_ws;
 154
 155     /* gomp_work_share structs are chained in the free work share cache
 156        through this.  */
 157     struct gomp_work_share *next_free;
 158   };
 159
 160   /* If only few threads are in the team, ordered_team_ids can point
 161      to this array which fills the padding at the end of this struct.  */
 162   unsigned inline_ordered_team_ids[0];
 163 };
 164
 165 /* This structure contains all of the thread-local data associated with
 166    a thread team.  This is the data that must be saved when a thread
 167    encounters a nested PARALLEL construct.  */
 168
 169 struct gomp_team_state
 170 {
 171   /* This is the team of which the thread is currently a member.  */
 172   struct gomp_team *team;
 173
 174   /* This is the work share construct which this thread is currently
 175      processing.  Recall that with NOWAIT, not all threads may be
 176      processing the same construct.  */
 177   struct gomp_work_share *work_share;
 178
 179   /* This is the previous work share construct or NULL if there wasn't any.
 180      When all threads are done with the current work sharing construct,
 181      the previous one can be freed.  The current one can't, as its
 182      next_ws field is used.  */
 183   struct gomp_work_share *last_work_share;
 184
 185   /* This is the ID of this thread within the team.  This value is
 186      guaranteed to be between 0 and N-1, where N is the number of
 187      threads in the team.  */
 188   unsigned team_id;
 189
 190   /* Nesting level.  */
 191   unsigned level;
 192
 193   /* Active nesting level.  Only active parallel regions are counted.  */
 194   unsigned active_level;
 195
 196 #ifdef HAVE_SYNC_BUILTINS
 197   /* Number of single stmts encountered.  */
 198   unsigned long single_count;
 199 #endif
 200
 201   /* For GFS_RUNTIME loops that resolved to GFS_STATIC, this is the
 202      trip number through the loop.  So first time a particular loop
 203      is encountered this number is 0, the second time through the loop
 204      is 1, etc.  This is unused when the compiler knows in advance that
 205      the loop is statically scheduled.  */
 206   unsigned long static_trip;
 207 };
 208
 209 /* These are the OpenMP 3.0 Internal Control Variables described in
 210    section 2.3.1.  Those described as having one copy per task are
 211    stored within the structure; those described as having one copy
 212    for the whole program are (naturally) global variables.  */
 213
 214 struct gomp_task_icv
 215 {
 216   unsigned long nthreads_var;
 217   enum gomp_schedule_type run_sched_var;
 218   int run_sched_modifier;
 219   bool dyn_var;
 220   bool nest_var;
 221 };
 222
 223 extern struct gomp_task_icv gomp_global_icv;
 224 extern unsigned long gomp_thread_limit_var;
 225 extern unsigned long gomp_remaining_threads_count;
 226 #ifndef HAVE_SYNC_BUILTINS
 227 extern gomp_mutex_t gomp_remaining_threads_lock;
 228 #endif
 229 extern unsigned long gomp_max_active_levels_var;
 230 extern unsigned long long gomp_spin_count_var, gomp_throttled_spin_count_var;
 231 extern unsigned long gomp_available_cpus, gomp_managed_threads;
 232
 233 enum gomp_task_kind
 234 {
 235   GOMP_TASK_IMPLICIT,
 236   GOMP_TASK_IFFALSE,
 237   GOMP_TASK_WAITING,
 238   GOMP_TASK_TIED
 239 };
 240
 241 /* This structure describes a "task" to be run by a thread.  */
 242
 243 struct gomp_task
 244 {
 245   struct gomp_task *parent;
 246   struct gomp_task *children;
 247   struct gomp_task *next_child;
 248   struct gomp_task *prev_child;
 249   struct gomp_task *next_queue;
 250   struct gomp_task *prev_queue;
 251   struct gomp_task_icv icv;
 252   void (*fn) (void *);
 253   void *fn_data;
 254   enum gomp_task_kind kind;
 255   bool in_taskwait;
 256   gomp_sem_t taskwait_sem;
 257 };
 258
 259 /* This structure describes a "team" of threads.  These are the threads
 260    that are spawned by a PARALLEL constructs, as well as the work sharing
 261    constructs that the team encounters.  */
 262
 263 struct gomp_team
 264 {
 265   /* This is the number of threads in the current team.  */
 266   unsigned nthreads;
 267
 268   /* This is number of gomp_work_share structs that have been allocated
 269      as a block last time.  */
 270   unsigned work_share_chunk;
 271
 272   /* This is the saved team state that applied to a master thread before
 273      the current thread was created.  */
 274   struct gomp_team_state prev_ts;
 275
 276   /* This semaphore should be used by the master thread instead of its
 277      "native" semaphore in the thread structure.  Required for nested
 278      parallels, as the master is a member of two teams.  */
 279   gomp_sem_t master_release;
 280
 281   /* This points to an array with pointers to the release semaphore
 282      of the threads in the team.  */
 283   gomp_sem_t **ordered_release;
 284
 285   /* List of gomp_work_share structs chained through next_free fields.
 286      This is populated and taken off only by the first thread in the
 287      team encountering a new work sharing construct, in a critical
 288      section.  */
 289   struct gomp_work_share *work_share_list_alloc;
 290
 291   /* List of gomp_work_share structs freed by free_work_share.  New
 292      entries are atomically added to the start of the list, and
 293      alloc_work_share can safely only move all but the first entry
 294      to work_share_list alloc, as free_work_share can happen concurrently
 295      with alloc_work_share.  */
 296   struct gomp_work_share *work_share_list_free;
 297
 298 #ifdef HAVE_SYNC_BUILTINS
 299   /* Number of simple single regions encountered by threads in this
 300      team.  */
 301   unsigned long single_count;
 302 #else
 303   /* Mutex protecting addition of workshares to work_share_list_free.  */
 304   gomp_mutex_t work_share_list_free_lock;
 305 #endif
 306
 307   /* This barrier is used for most synchronization of the team.  */
 308   gomp_barrier_t barrier;
 309
 310   /* Initial work shares, to avoid allocating any gomp_work_share
 311      structs in the common case.  */
 312   struct gomp_work_share work_shares[8];
 313
 314   gomp_mutex_t task_lock;
 315   struct gomp_task *task_queue;
 316   int task_count;
 317   int task_running_count;
 318
 319   /* This array contains structures for implicit tasks.  */
 320   struct gomp_task implicit_task[];
 321 };
 322
 323 /* This structure contains all data that is private to libgomp and is
 324    allocated per thread.  */
 325
 326 struct gomp_thread
 327 {
 328   /* This is the function that the thread should run upon launch.  */
 329   void (*fn) (void *data);
 330   void *data;
 331
 332   /* This is the current team state for this thread.  The ts.team member
 333      is NULL only if the thread is idle.  */
 334   struct gomp_team_state ts;
 335
 336   /* This is the task that the thread is currently executing.  */
 337   struct gomp_task *task;
 338
 339   /* This semaphore is used for ordered loops.  */
 340   gomp_sem_t release;
 341
 342   /* user pthread thread pool */
 343   struct gomp_thread_pool *thread_pool;
 344 };
 345
 346
 347 struct gomp_thread_pool
 348 {
 349   /* This array manages threads spawned from the top level, which will
 350      return to the idle loop once the current PARALLEL construct ends.  */
 351   struct gomp_thread **threads;
 352   unsigned threads_size;
 353   unsigned threads_used;
 354   struct gomp_team *last_team;
 355
 356   /* This barrier holds and releases threads waiting in threads.  */
 357   gomp_barrier_t threads_dock;
 358 };
 359
 360 /* ... and here is that TLS data.  */
 361
 362 #ifdef HAVE_TLS
 363 extern __thread struct gomp_thread gomp_tls_data;
 364 static inline struct gomp_thread *gomp_thread (void)
 365 {
 366   return &gomp_tls_data;
 367 }
 368 #else
 369 extern pthread_key_t gomp_tls_key;
 370 static inline struct gomp_thread *gomp_thread (void)
 371 {
 372   return pthread_getspecific (gomp_tls_key);
 373 }
 374 #endif
 375
 376 extern struct gomp_task_icv *gomp_new_icv (void);
 377
 378 /* Here's how to access the current copy of the ICVs.  */
 379
 380 static inline struct gomp_task_icv *gomp_icv (bool write)
 381 {
 382   struct gomp_task *task = gomp_thread ()->task;
 383   if (task)
 384     return &task->icv;
 385   else if (write)
 386     return gomp_new_icv ();
 387   else
 388     return &gomp_global_icv;
 389 }
 390
 391 /* The attributes to be used during thread creation.  */
 392 extern pthread_attr_t gomp_thread_attr;
 393
 394 /* Other variables.  */
 395
 396 extern unsigned short *gomp_cpu_affinity;
 397 extern size_t gomp_cpu_affinity_len;
 398
 399 /* Function prototypes.  */
 400
 401 /* affinity.c */
 402
 403 extern void gomp_init_affinity (void);
 404 extern void gomp_init_thread_affinity (pthread_attr_t *);
 405
 406 /* alloc.c */
 407
 408 extern void *gomp_malloc (size_t) __attribute__((malloc));
 409 extern void *gomp_malloc_cleared (size_t) __attribute__((malloc));
 410 extern void *gomp_realloc (void *, size_t);
 411
 412 /* Avoid conflicting prototypes of alloca() in system headers by using
 413    GCC's builtin alloca().  */
 414 #define gomp_alloca(x)  __builtin_alloca(x)
 415
 416 /* error.c */
 417
 418 extern void gomp_error (const char *, ...)
 419         __attribute__((format (printf, 1, 2)));
 420 extern void gomp_fatal (const char *, ...)
 421         __attribute__((noreturn, format (printf, 1, 2)));
 422
 423 /* iter.c */
 424
 425 extern int gomp_iter_static_next (long *, long *);
 426 extern bool gomp_iter_dynamic_next_locked (long *, long *);
 427 extern bool gomp_iter_guided_next_locked (long *, long *);
 428
 429 #ifdef HAVE_SYNC_BUILTINS
 430 extern bool gomp_iter_dynamic_next (long *, long *);
 431 extern bool gomp_iter_guided_next (long *, long *);
 432 #endif
 433
 434 /* iter_ull.c */
 435
 436 extern int gomp_iter_ull_static_next (unsigned long long *,
 437                                       unsigned long long *);
 438 extern bool gomp_iter_ull_dynamic_next_locked (unsigned long long *,
 439                                                unsigned long long *);
 440 extern bool gomp_iter_ull_guided_next_locked (unsigned long long *,
 441                                               unsigned long long *);
 442
 443 #if defined HAVE_SYNC_BUILTINS && defined __LP64__
 444 extern bool gomp_iter_ull_dynamic_next (unsigned long long *,
 445                                         unsigned long long *);
 446 extern bool gomp_iter_ull_guided_next (unsigned long long *,
 447                                        unsigned long long *);
 448 #endif
 449
 450 /* ordered.c */
 451
 452 extern void gomp_ordered_first (void);
 453 extern void gomp_ordered_last (void);
 454 extern void gomp_ordered_next (void);
 455 extern void gomp_ordered_static_init (void);
 456 extern void gomp_ordered_static_next (void);
 457 extern void gomp_ordered_sync (void);
 458
 459 /* parallel.c */
 460
 461 extern unsigned gomp_resolve_num_threads (unsigned, unsigned);
 462
 463 /* proc.c (in config/) */
 464
 465 extern void gomp_init_num_threads (void);
 466 extern unsigned gomp_dynamic_max_threads (void);
 467
 468 /* task.c */
 469
 470 extern void gomp_init_task (struct gomp_task *, struct gomp_task *,
 471                             struct gomp_task_icv *);
 472 extern void gomp_end_task (void);
 473 extern void gomp_barrier_handle_tasks (gomp_barrier_state_t);
 474
 475 static void inline
 476 gomp_finish_task (struct gomp_task *task)
 477 {
 478   gomp_sem_destroy (&task->taskwait_sem);
 479 }
 480
 481 /* team.c */
 482
 483 extern struct gomp_team *gomp_new_team (unsigned);
 484 extern void gomp_team_start (void (*) (void *), void *, unsigned,
 485                              struct gomp_team *);
 486 extern void gomp_team_end (void);
 487
 488 /* work.c */
 489
 490 extern void gomp_init_work_share (struct gomp_work_share *, bool, unsigned);
 491 extern void gomp_fini_work_share (struct gomp_work_share *);
 492 extern bool gomp_work_share_start (bool);
 493 extern void gomp_work_share_end (void);
 494 extern void gomp_work_share_end_nowait (void);
 495
 496 static inline void
 497 gomp_work_share_init_done (void)
 498 {
 499   struct gomp_thread *thr = gomp_thread ();
 500   if (__builtin_expect (thr->ts.last_work_share != NULL, 1))
 501     gomp_ptrlock_set (&thr->ts.last_work_share->next_ws, thr->ts.work_share);
 502 }
 503
 504 #ifdef HAVE_ATTRIBUTE_VISIBILITY
 505 # pragma GCC visibility pop
 506 #endif
 507
 508 /* Now that we're back to default visibility, include the globals.  */
 509 #include "libgomp_g.h"
 510
 511 /* Include omp.h by parts.  */
 512 #include "omp-lock.h"
 513 #define _LIBGOMP_OMP_LOCK_DEFINED 1
 514 #include "omp.h.in"
 515
 516 #if !defined (HAVE_ATTRIBUTE_VISIBILITY) \
 517     || !defined (HAVE_ATTRIBUTE_ALIAS) \
 518     || !defined (PIC)
 519 # undef LIBGOMP_GNU_SYMBOL_VERSIONING
 520 #endif
 521
 522 #ifdef LIBGOMP_GNU_SYMBOL_VERSIONING
 523 extern void gomp_init_lock_30 (omp_lock_t *) __GOMP_NOTHROW;
 524 extern void gomp_destroy_lock_30 (omp_lock_t *) __GOMP_NOTHROW;
 525 extern void gomp_set_lock_30 (omp_lock_t *) __GOMP_NOTHROW;
 526 extern void gomp_unset_lock_30 (omp_lock_t *) __GOMP_NOTHROW;
 527 extern int gomp_test_lock_30 (omp_lock_t *) __GOMP_NOTHROW;
 528 extern void gomp_init_nest_lock_30 (omp_nest_lock_t *) __GOMP_NOTHROW;
 529 extern void gomp_destroy_nest_lock_30 (omp_nest_lock_t *) __GOMP_NOTHROW;
 530 extern void gomp_set_nest_lock_30 (omp_nest_lock_t *) __GOMP_NOTHROW;
 531 extern void gomp_unset_nest_lock_30 (omp_nest_lock_t *) __GOMP_NOTHROW;
 532 extern int gomp_test_nest_lock_30 (omp_nest_lock_t *) __GOMP_NOTHROW;
 533
 534 extern void gomp_init_lock_25 (omp_lock_25_t *) __GOMP_NOTHROW;
 535 extern void gomp_destroy_lock_25 (omp_lock_25_t *) __GOMP_NOTHROW;
 536 extern void gomp_set_lock_25 (omp_lock_25_t *) __GOMP_NOTHROW;
 537 extern void gomp_unset_lock_25 (omp_lock_25_t *) __GOMP_NOTHROW;
 538 extern int gomp_test_lock_25 (omp_lock_25_t *) __GOMP_NOTHROW;
 539 extern void gomp_init_nest_lock_25 (omp_nest_lock_25_t *) __GOMP_NOTHROW;
 540 extern void gomp_destroy_nest_lock_25 (omp_nest_lock_25_t *) __GOMP_NOTHROW;
 541 extern void gomp_set_nest_lock_25 (omp_nest_lock_25_t *) __GOMP_NOTHROW;
 542 extern void gomp_unset_nest_lock_25 (omp_nest_lock_25_t *) __GOMP_NOTHROW;
 543 extern int gomp_test_nest_lock_25 (omp_nest_lock_25_t *) __GOMP_NOTHROW;
 544
 545 # define strong_alias(fn, al) \
 546   extern __typeof (fn) al __attribute__ ((alias (#fn)));
 547 # define omp_lock_symver(fn) \
 548   __asm (".symver g" #fn "_30, " #fn "@@OMP_3.0"); \
 549   __asm (".symver g" #fn "_25, " #fn "@OMP_1.0");
 550 #else
 551 # define gomp_init_lock_30 omp_init_lock
 552 # define gomp_destroy_lock_30 omp_destroy_lock
 553 # define gomp_set_lock_30 omp_set_lock
 554 # define gomp_unset_lock_30 omp_unset_lock
 555 # define gomp_test_lock_30 omp_test_lock
 556 # define gomp_init_nest_lock_30 omp_init_nest_lock
 557 # define gomp_destroy_nest_lock_30 omp_destroy_nest_lock
 558 # define gomp_set_nest_lock_30 omp_set_nest_lock
 559 # define gomp_unset_nest_lock_30 omp_unset_nest_lock
 560 # define gomp_test_nest_lock_30 omp_test_nest_lock
 561 #endif
 562
 563 #ifdef HAVE_ATTRIBUTE_VISIBILITY
 564 # define attribute_hidden __attribute__ ((visibility ("hidden")))
 565 #else
 566 # define attribute_hidden
 567 #endif
 568
 569 #ifdef HAVE_ATTRIBUTE_ALIAS
 570 # define ialias(fn) \
 571   extern __typeof (fn) gomp_ialias_##fn \
 572     __attribute__ ((alias (#fn))) attribute_hidden;
 573 #else
 574 # define ialias(fn)
 575 #endif
 576
 577 #endif /* LIBGOMP_H */