workstealing.h
Go to the documentation of this file.
// -*- C++ -*-
// Copyright (C) 2007-2026 Free Software Foundation, Inc.
//
// This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the terms
// of the GNU General Public License as published by the Free Software
// Foundation; either version 3, or (at your option) any later
// version.
// This library is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
// Under Section 7 of GPL version 3, you are granted additional
// permissions described in the GCC Runtime Library Exception, version
// 3.1, as published by the Free Software Foundation.
// You should have received a copy of the GNU General Public License and
// a copy of the GCC Runtime Library Exception along with this program;
// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
// <http://www.gnu.org/licenses/>.
/** @file parallel/workstealing.h
* @brief Parallelization of embarrassingly parallel execution by
* means of work-stealing.
*
* Work stealing is described in
*
* R. D. Blumofe and C. E. Leiserson.
* Scheduling multithreaded computations by work stealing.
* Journal of the ACM, 46(5):720-748, 1999.
*
* This file is a GNU parallel extension to the Standard C++ Library.
*/
// Written by Felix Putze.
#ifndef _GLIBCXX_PARALLEL_WORKSTEALING_H
#define _GLIBCXX_PARALLEL_WORKSTEALING_H 1
#include <parallel/parallel.h>
#include <parallel/random_number.h>
#include <parallel/compatibility.h>
namespace __gnu_parallel
{
#define _GLIBCXX_JOB_VOLATILE volatile
/** @brief One __job for a certain thread. */
template<typename _DifferenceTp>
struct _Job
{
typedef _DifferenceTp _DifferenceType;
/** @brief First element.
*
* Changed by owning and stealing thread. By stealing thread,
* always incremented. */
_GLIBCXX_JOB_VOLATILE _DifferenceType _M_first;
/** @brief Last element.
*
* Changed by owning thread only. */
_GLIBCXX_JOB_VOLATILE _DifferenceType _M_last;
/** @brief Number of elements, i.e. @c _M_last-_M_first+1.
*
* Changed by owning thread only. */
_GLIBCXX_JOB_VOLATILE _DifferenceType _M_load;
};
/** @brief Work stealing algorithm for random access iterators.
*
* Uses O(1) additional memory. Synchronization at job lists is
* done with atomic operations.
* @param __begin Begin iterator of element sequence.
* @param __end End iterator of element sequence.
* @param __op User-supplied functor (comparator, predicate, adding
* functor, ...).
* @param __f Functor to @a process an element with __op (depends on
* desired functionality, e. g. for std::for_each(), ...).
* @param __r Functor to @a add a single __result to the already
* processed elements (depends on functionality).
* @param __base Base value for reduction.
* @param __output Pointer to position where final result is written to
* @param __bound Maximum number of elements processed (e. g. for
* std::count_n()).
* @return User-supplied functor (that may contain a part of the result).
*/
template<typename _RAIter,
typename _Op,
typename _Fu,
typename _Red,
typename _Result>
_Op
__for_each_template_random_access_workstealing(_RAIter __begin,
_RAIter __end, _Op __op,
_Fu& __f, _Red __r,
_Result __base,
_Result& __output,
typename std::iterator_traits<_RAIter>::difference_type __bound)
{
_GLIBCXX_CALL(__end - __begin)
typedef std::iterator_traits<_RAIter> _TraitsType;
typedef typename _TraitsType::difference_type _DifferenceType;
const _Settings& __s = _Settings::get();
_DifferenceType __chunk_size =
static_cast<_DifferenceType>(__s.workstealing_chunk_size);
// How many jobs?
_DifferenceType __length = (__bound < 0) ? (__end - __begin) : __bound;
// To avoid false sharing in a cache line.
const int __stride = (__s.cache_line_size * 10
/ sizeof(_Job<_DifferenceType>) + 1);
// Total number of threads currently working.
_ThreadIndex __busy = 0;
_Job<_DifferenceType> *__job;
omp_lock_t __output_lock;
omp_init_lock(&__output_lock);
// Write base value to output.
__output = __base;
// No more threads than jobs, at least one thread.
_ThreadIndex __num_threads = __gnu_parallel::max<_ThreadIndex>
(1, __gnu_parallel::min<_DifferenceType>(__length,
__get_max_threads()));
# pragma omp parallel shared(__busy) num_threads(__num_threads)
{
# pragma omp single
{
__num_threads = omp_get_num_threads();
// Create job description array.
__job = new _Job<_DifferenceType>[__num_threads * __stride];
}
// Initialization phase.
// Flags for every thread if it is doing productive work.
bool __iam_working = false;
// Thread id.
_ThreadIndex __iam = omp_get_thread_num();
// This job.
_Job<_DifferenceType>& __my_job = __job[__iam * __stride];
// Random number (for work stealing).
_ThreadIndex __victim;
// Local value for reduction.
_Result __result = _Result();
// Number of elements to steal in one attempt.
_DifferenceType __steal;
// Every thread has its own random number generator
// (modulo __num_threads).
_RandomNumber __rand_gen(__iam, __num_threads);
// This thread is currently working.
# pragma omp atomic
++__busy;
__iam_working = true;
// How many jobs per thread? last thread gets the rest.
__my_job._M_first = static_cast<_DifferenceType>
(__iam * (__length / __num_threads));
__my_job._M_last = (__iam == (__num_threads - 1)
? (__length - 1)
: ((__iam + 1) * (__length / __num_threads) - 1));
__my_job._M_load = __my_job._M_last - __my_job._M_first + 1;
// Init result with _M_first value (to have a base value for reduction)
if (__my_job._M_first <= __my_job._M_last)
{
// Cannot use volatile variable directly.
_DifferenceType __my_first = __my_job._M_first;
__result = __f(__op, __begin + __my_first);
__my_job._M_first += 1;
__my_job._M_load -= 1;
}
_RAIter __current;
# pragma omp barrier
// Actual work phase
// Work on own or stolen current start
while (__busy > 0)
{
// Work until no productive thread left.
# pragma omp flush(__busy)
// Thread has own work to do
while (__my_job._M_first <= __my_job._M_last)
{
// fetch-and-add call
// Reserve current job block (size __chunk_size) in my queue.
_DifferenceType __current_job =
__fetch_and_add<_DifferenceType>(&(__my_job._M_first),
__chunk_size);
// Update _M_load, to make the three values consistent,
// _M_first might have been changed in the meantime
__my_job._M_load = __my_job._M_last - __my_job._M_first + 1;
for (_DifferenceType __job_counter = 0;
__job_counter < __chunk_size
&& __current_job <= __my_job._M_last;
++__job_counter)
{
// Yes: process it!
__current = __begin + __current_job;
++__current_job;
// Do actual work.
__result = __r(__result, __f(__op, __current));
}
# pragma omp flush(__busy)
}
// After reaching this point, a thread's __job list is empty.
if (__iam_working)
{
// This thread no longer has work.
# pragma omp atomic
--__busy;
__iam_working = false;
}
_DifferenceType __supposed_first, __supposed_last,
__supposed_load;
do
{
// Find random nonempty deque (not own), do consistency check.
__yield();
# pragma omp flush(__busy)
__victim = __rand_gen();
__supposed_first = __job[__victim * __stride]._M_first;
__supposed_last = __job[__victim * __stride]._M_last;
__supposed_load = __job[__victim * __stride]._M_load;
}
while (__busy > 0
&& ((__supposed_load <= 0)
|| ((__supposed_first + __supposed_load - 1)
!= __supposed_last)));
if (__busy == 0)
break;
if (__supposed_load > 0)
{
// Has work and work to do.
// Number of elements to steal (at least one).
__steal = (__supposed_load < 2) ? 1 : __supposed_load / 2;
// Push __victim's current start forward.
_DifferenceType __stolen_first =
__fetch_and_add<_DifferenceType>
(&(__job[__victim * __stride]._M_first), __steal);
_DifferenceType __stolen_try = (__stolen_first + __steal
- _DifferenceType(1));
__my_job._M_first = __stolen_first;
__my_job._M_last = __gnu_parallel::min(__stolen_try,
__supposed_last);
__my_job._M_load = __my_job._M_last - __my_job._M_first + 1;
// Has potential work again.
# pragma omp atomic
++__busy;
__iam_working = true;
# pragma omp flush(__busy)
}
# pragma omp flush(__busy)
} // end while __busy > 0
// Add accumulated result to output.
omp_set_lock(&__output_lock);
__output = __r(__output, __result);
omp_unset_lock(&__output_lock);
}
delete[] __job;
// Points to last element processed (needed as return value for
// some algorithms like transform)
__f._M_finish_iterator = __begin + __length;
omp_destroy_lock(&__output_lock);
return __op;
}
} // end namespace
#endif /* _GLIBCXX_PARALLEL_WORKSTEALING_H */
parallel.h
End-user include file. Provides advanced settings and tuning options. This file is a GNU parallel ext...
_GLIBCXX_CALL
#define _GLIBCXX_CALL(__n)
Macro to produce log message when entering a function.
Definition compiletime_settings.h:44
random_number.h
Random number generator based on the Mersenne twister. This file is a GNU parallel extension to the S...
__gnu_parallel
GNU parallel code for public use.
Definition balanced_quicksort.h:62
__gnu_parallel::_ThreadIndex
uint16_t _ThreadIndex
Unsigned integer to index a thread number. The maximum thread number (for each processor) must fit in...
Definition types.h:123
__gnu_parallel::__for_each_template_random_access_workstealing
_Op __for_each_template_random_access_workstealing(_RAIter __begin, _RAIter __end, _Op __op, _Fu &__f, _Red __r, _Result __base, _Result &__output, typename std::iterator_traits< _RAIter >::difference_type __bound)
Work stealing algorithm for random access iterators.
Definition workstealing.h:99
__gnu_parallel::max
const _Tp & max(const _Tp &__a, const _Tp &__b)
Equivalent to std::max.
Definition base.h:150
__gnu_parallel::min
const _Tp & min(const _Tp &__a, const _Tp &__b)
Equivalent to std::min.
Definition base.h:144
__gnu_parallel::__fetch_and_add
_Tp __fetch_and_add(volatile _Tp *__ptr, _Tp __addend)
Add a value to a variable, atomically.
Definition parallel/compatibility.h:74
__gnu_parallel::__yield
void __yield()
Yield control to another thread, without waiting for the end of the time slice.
Definition parallel/compatibility.h:121
std::iterator_traits
Traits class for iterators.
Definition stl_iterator_base_types.h:180
__gnu_parallel::_RandomNumber
Random number generator, based on the Mersenne twister.
Definition random_number.h:46
__gnu_parallel::_Settings
class _Settings Run-time settings for the parallel mode including all tunable parameters.
Definition settings.h:126
__gnu_parallel::_Settings::cache_line_size
unsigned int cache_line_size
Overestimation of cache line size. Used to avoid false sharing, i.e. elements of different threads ar...
Definition settings.h:267
__gnu_parallel::_Settings::get
static const _Settings & get()
Get the global settings.
__gnu_parallel::_Job
One __job for a certain thread.
Definition workstealing.h:55
__gnu_parallel::_Job::_M_load
volatile _DifferenceType _M_load
Number of elements, i.e. _M_last-_M_first+1.
Definition workstealing.h:72
__gnu_parallel::_Job::_M_last
volatile _DifferenceType _M_last
Last element.
Definition workstealing.h:67
__gnu_parallel::_Job::_M_first
volatile _DifferenceType _M_first
First element.
Definition workstealing.h:62
compatibility.h
Compatibility layer, mostly concerned with atomic operations.