/Volumes/unix-files/u/ntl-new/ntl-9.10.0dev/doc/BasicThreadPool.cpp.html

/************************************************************************
MODULE: BasicThreadPool
SUMMARY:
A simple thread pool class BasicThreadPool, as well as some higher-level macros
which facilitite simple parallel for loops.
***************************************************************************/
// ********************** Simple parallel for loops **************************
//
// We begin with a description of the higher-level macros for writing simple
// parallel for loops. These facilitaties are activated only when NTL is
// configured with NTL_THREAD_BOOST=on (which implies NTL_THREADS=on).
// However, code that uses these facilties should still compile and run
// correctly even when NTL_THREAD_BOOST=off, or even when NTL_THREADS=off, so
// this is the simplest way to write parallel for loops across a range of
// compile-time and run-time environments. Note that if NTL_THREADS=on, C++11
// features are reqired, but when NTL_THREADS=off, these features are not
// required, so the code should compile on older C++ compilers.
//
// Here is a simple recipe for writing parallel for loop.
//
// At the start of program execution, your program should execute
SetNumThreads(nt);
// You can choose nt to be any positive integer, but for best results, it
// should correspond to the number of available cores on your machine.
// [NOTE: if NTL_THREAD_BOOST=off, this function is still defined, but does
// nothing.]
//
// Now consider the following routine:
void mul(ZZ *x, const ZZ *a, const ZZ *b, long n)
{
for (long i = 0; i < n; i++)
mul(x[i], a[i], b[i]);
}
// We can parallelize it as follows:
void mul(ZZ *x, const ZZ *a, const ZZ *b, long n)
{
NTL_EXEC_RANGE(n, first, last)
for (long i = first; i < last; i++)
mul(x[i], a[i], b[i]);
NTL_EXEC_RANGE_END
}
// NTL_EXEC_RANGE and NTL_EXEC_RANGE_END are macros that just "do the right
// thing". If there are nt threads available, the interval [0..n) will be
// partitioned into (up to) nt subintervals, and a different thread will be
// used to process each subinterval. You still have to write the for loop
// yourself: the macro just declares and initializes variables "first" and
// "last" (or whatever you want to call them) of type long that represent the
// subinterval [first..last) to be processed by one thread.
//
// Note that the current thread participates as one of the nt available
// threads, and that the current thread will wait for all other participating threads
// to finish their task before proceeding. The current thread can be identified
// as the one with first == 0.
//
// Withing the "body" of this construct, you can freely reference any variables
// that are visible at this point. This is implemented using the C++ lambda
// feature (capturing all variables by reference).
//
// This construct will still work even if threads are disabled, in which case
// it runs single-threaded with first=0 and last=n.
//
// Note that the code within the EXEC_RANGE body could call other routines that
// themselves attempt to execute an EXEC_RANGE: if this happens, the latter
// EXEC_RANGE will detect this and run single-threaded.
//
// You may wish to do other things within the EXEC_RANGE body than just execute
// a loop. One thing you may want to do is to declare variables. Another
// thing you may want to do is setup a local context for a ZZ_p modulus (or
// other type of modulus). Here is an example of doing this:
void mul(ZZ_p *x, const ZZ_p *a, const ZZ_p *b, long n)
{
ZZ_pContext context;
context.save();
NTL_EXEC_RANGE(n, first, last)
context.restore();
for (long i = first; i < last; i++)
mul(x[i], a[i], b[i]);
NTL_EXEC_RANGE_END
}
// Another useful function is AvailableThreads(), which will return the number
// of available threads. If threads or thread boosting is not enabled, this
// will return 1. Even if thread boosting is enabled, this may return 1 if for
// whatever reason, the thread pool is not available for use (for example,
// SetNumThreads was never called, or the thread pool is already active).
//
// A lower-level set of tools is available, which allow you to simply run a
// specified number of threads. Assuming nt <= AvailableThreads(), the code
NTL_EXEC_INDEX(nt, index)
... code ...
NTL_EXEC_INDEX_END
// will execute the body on nt different threads, each with a unique index in
// the range [0..nt). A variable named "index" (or whatever name you specify)
// of type long will hold the given index. Just as with EXEC_RANGE, the current
// thread will participate as one of the nt threads, and will always be
// assigned an index of 0.
//
// This tool is useful if you need to manage memory a bit more carefully. For
// example, the following code will compute an inner product using all
// available threads:
ZZ InnerProd(const ZZ *a, const ZZ *b, long n)
{
PartitionInfo pinfo(n);
long cnt = pinfo.NumIntervals();
Vec<ZZ> acc;
acc.SetLength(cnt);
NTL_EXEC_INDEX(cnt, index)
long first, last;
pinfo.interval(first, last, index);
ZZ& sum = acc[index];
sum = 0;
for (long i = first; i < last; i++)
MulAddTo(sum, a[i], b[i]);
NTL_EXEC_INDEX_END
ZZ sum;
sum = 0;
for (long i = 0; i < cnt; i++)
sum += acc[i];
return sum;
}
// This example also illustrates the class PartitionInfo, which is useful for
// partitioning a large interval into smaller intervals (it is used internally
// by EXEC_RANGE). The constructor takes a single argument (in this example n)
// and computes a partition of [0..n) into nearly equally sized subintervals.
// The method NumIntervals() returns the number of subintervals, and the method
// interval(first, last, index) sets first and last according to the endpoints
// of the subinterval [first..last) with the given index.
//
// So in this example, cnt threads will run, each accumulating a sum into a
// corresponding element of the vector acc, and afterwords, these elements are
// summed.
//
// Note that if threads are not enabled or otherwise unavailable, the above
// code will compile and run correctly (just using one thread).
//
// Finally, there is a "guarded" version of NTL_EXEC_RANGE called
// NTL_GEXEC_RANGE. This allows one to dynamically "guard" against parallel
// execution. For example, on very small problems the runtime overhead of a
// parallel for loop may not be worthwhile, or in other situations parallel
// execution could cause incorrect behavior. See below for details.
// ************************** Thread Pools ******************************
//
// The above facilities are built on top of a more general thread pool class,
// which you may use for your own purposes.
//
// You create a thread pool by constructing a BasicThreadPool object. For
// example:
long nthreads = 4;
BasicThreadPool pool(nthreads);
// creates a thread pool of 4 threads. These threads will exist until the
// destructor for pool is called.
//
// The simplest way to use a thread pools is as follows. Suppose you have a
// task that consists of sz subtasks, indexed 0..sz-1. Then you can write:
pool.exec_range(sz,
[&](long first, long last) {
for (long i = first; i < last; i++) {
... code to process subtask i ...
}
}
);
// The second argument to exec_range is a C++11 "lambda". The "[&]" indicates
// that all local variables in the calling context are captured by reference,
// so the lambda body can reference all visible local variables directly.
// C++11 provides other methods for capturing local variables. The interval
// [0..sz) is partitioned into subintervals of the form [first..last), which
// are processed by the code in the supplied lambda.
//
// A lower-level interface is also provided. One can write:
pool.exec_index(cnt,
[&](long index) {
... code to process index i ...
}
);
// This will activate exactly cnt threads with indices 0..cnt-1, and execute
// the given code on each index. The parameter cnt must not exceed nthreads,
// otherwise an error is raised.
// ====================================================================
//
// NOTES:
//
// When one activates a thread pool with nthreads threads, the *current* thread
// (the one activating the pool) will also participate in the computation.
// This means that the thread pool only contains nthreads-1 other threads.
//
// If, during an activation, any thread throws an exception, it will be caught
// and rethrown in the activating thread when all the threads complete. If
// more than one thread throws an exception, the first one that is caught is
// the one that is rethrown.
//
// Methods are also provided for adding, deleting, and moving threads in and
// among thread pools.
//
// If NTL_THREADS=off, the corresponding header file may be included, but the
// BasicThreadPool class is not defined.
//
// Unlike most classes in NTL, the BasicThreadPool is not relocatable and hence
// cannot be used in a Vec. One should first wrap it in a pointer class, such
// as UniquePtr.
// class BasicThreadPool: provided basic functionality for thread pools
class BasicThreadPool {
private:
BasicThreadPool(const BasicThreadPool&); // disabled
void operator=(const BasicThreadPool&); // disabled
public:
explicit
BasicThreadPool(long nthreads);
// creates a pool with nthreads threads, including the current thread
// (so nthreads-1 other threads get created)
template<class Fct>
void exec_range(long sz, const Fct& fct);
// activate by range (see example usage above)
template<class Fct>
void exec_index(long cnt, const Fct& fct);
// activate by index (see example usage above)
void add(long n = 1);
// add n threads to the pool
long NumThreads() const;
// return number of threads (including current thread)
void remove(long n = 1);
// remove n threads from the pool
void move(BasicThreadPool& other, long n = 1)
// move n threads from other pool to this pool
bool active() const;
// indicates an activation is in process: invoking any of the methods
// exec_index, exec_range, add, remove, move, or the destructor
// whie active will raise an error
template<class Fct>
static void relaxed_exec_range(BasicThreadPool *pool, long sz, const Fct& fct);
// similar to pool->exec_range(sz, fct), but will still work even
// if !pool or pool->active(), using just the current thread
template<class Fct>
static void relaxed_exec_index(BasicThreadPool *pool, long cnt, const Fct& fct);
// similar to pool->exec_index(cnt, fct), but will still work even
// if !pool or pool->active(), provided cnt <= 1, using just the current thread
};
// THREAD BOOSTING FEATURES:
void SetNumThreads(long nt);
// convenience routine to set NTL's thread pool.
// If called more than once, the old thread pool is destroyed and
// replaced by a new one.
// If NTL_THREAD_BOOST=off, then this is still defined, but does nothing.
long AvailableThreads();
// Number of threads currently availble to use in NTL's thread pool. This is
// always at least 1 (for the current thread).
// If NTL_THREAD_BOOST=off, then this is still defined, and always returns 1.
BasicThreadPool *GetThreadPool();
void ResetThreadPool(BasicThreadPool *pool = 0);
BasicThreadPool *ReleaseThreadPool();
// Routines to get and set NTL's thread pool. The interfaces parallel NTL's
// UniquePtr class, and indeed, behind the scenes, NTL's thread pool is stored
// as a UniquePtr<BasicThreadPool>.
// These are only declared when NTL_THREAD_BOOST=on.
#define NTL_EXEC_RANGE(sz, first, last) ...
#define NTL_EXEC_RANGE_END ...
#define NTL_EXEC_INDEX(cnt, index) ...
#define NTL_EXEC_INDEX_END ...
// convenience macros to implement "parallel for loops" using NTL's thread
// pool. See examples above for usage. If NTL_THREAD_BOOST=off, then these
// are still defined, and code will run on a single thread
#define NTL_GEXEC_RANGE(seq, sz, first, last) ...
#define NTL_GEXEC_RANGE_END ...
// "guarded" version of NTL_EXEC_RANGE: if seq evaluates to true, the code runs
// on a single thread. This is useful in avoiding situations where the
// overhead of a parallel loop is too high. If seq evaluates to the constant
// true, a good compiler will optimize code to run on a single thread, with no
// overhead.
#define NTL_IMPORT(x)
// To be used in conjunction with NTL_EXEC_RANGE and friends. When
// NTL_THREAD_BOOST=on, this will copy the variable named x from the enclosing
// scope to a local copy. This should only be used for types with cheap
// copies, such as scalars and pointers. In some situations, this allows the
// compiler to optimize a bit more aggressively. One or more of these may be
// placed right after an NTL_EXEC_RANGE.
// When NTL_THREAD_BOOST=off, this is still defined, and does nothing.
// class PartitionInfo: A helper class to facilitate partitioning an interval
// into subintervals. NOTE: this class is available, even when
// NTL_THREAD_BOOST=off.
class PartitionInfo {
public:
explicit
PartitionInfo(long sz, long nt = AvailableThreads());
// partitions [0..sz) into at most nt subintervals. sz may be 0 or
// negative, in which case the number of subintervals is 0.
long NumIntervals() const;
// return the number of subintervals
void interval(long& first, long& last, long i) const;
// [first..last) is the ith interval, where i in [0..NumInvervals()). No
// range checking is performed.
};