From: Wolfgang Bangerth Date: Sun, 21 Sep 2014 15:46:04 +0000 (-0500) Subject: Reindent all short comments to standard length. X-Git-Tag: v8.2.0-rc1~131^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3482c76cbc5d8f82261b11783936b17a51c3a426;p=dealii.git Reindent all short comments to standard length. --- diff --git a/include/deal.II/base/thread_management.h b/include/deal.II/base/thread_management.h index 7c8f53246c..ef5eb45c38 100644 --- a/include/deal.II/base/thread_management.h +++ b/include/deal.II/base/thread_management.h @@ -65,14 +65,15 @@ namespace Threads { /** * This class is used instead of a true lock class when not using - * multithreading. It allows to write programs such that they start new - * threads and/or lock objects in multithreading mode, and use dummy thread - * management and synchronization classes instead when running in - * single-thread mode. Specifically, the new_thread() functions only - * call the function but wait for it to return instead of running in on - * another thread, and the mutices do nothing really. The only reason to - * provide such a function is that the program can be compiled both in MT and - * non-MT mode without difference. + * multithreading. It allows to write programs such that they start + * new threads and/or lock objects in multithreading mode, and use + * dummy thread management and synchronization classes instead when + * running in single-thread mode. Specifically, the new_thread() + * functions only call the function but wait for it to return + * instead of running in on another thread, and the mutices do + * nothing really. The only reason to provide such a function is + * that the program can be compiled both in MT and non-MT mode + * without difference. * * @author Wolfgang Bangerth, 2000, 2003 */ @@ -80,73 +81,46 @@ namespace Threads { public: /** - * Scoped lock class. When you - * declare an object of this - * type, you have to pass it a - * mutex, which is locked in - * the constructor of this - * class and unlocked in the - * destructor. The lock is thus - * held during the entire - * lifetime of this object, - * i.e. until the end of the - * present scope, which - * explains where the name - * comes from. This pattern of - * using locks with mutexes - * follows the - * resource-acquisition-is-initialization - * pattern, and was used first - * for mutexes by Doug - * Schmidt. It has the - * advantage that locking a - * mutex this way is - * thread-safe, i.e. when an - * exception is thrown between - * the locking and unlocking - * point, the destructor makes - * sure that the mutex is - * unlocked; this would not - * automatically be the case - * when you lock and unlock the - * mutex "by hand", i.e. using - * acquire() and release(). + * Scoped lock class. When you declare an object of this type, you + * have to pass it a mutex, which is locked in the constructor of + * this class and unlocked in the destructor. The lock is thus + * held during the entire lifetime of this object, i.e. until the + * end of the present scope, which explains where the name comes + * from. This pattern of using locks with mutexes follows the + * resource-acquisition-is-initialization pattern, and was used + * first for mutexes by Doug Schmidt. It has the advantage that + * locking a mutex this way is thread-safe, i.e. when an exception + * is thrown between the locking and unlocking point, the + * destructor makes sure that the mutex is unlocked; this would + * not automatically be the case when you lock and unlock the + * mutex "by hand", i.e. using acquire() and + * release(). */ class ScopedLock { public: /** - * Constructor. Lock the - * mutex. Since this is a - * dummy mutex class, this - * of course does nothing. + * Constructor. Lock the mutex. Since this is a dummy mutex + * class, this of course does nothing. */ ScopedLock (DummyThreadMutex &) {} /** - * Destructor. Unlock the - * mutex. Since this is a - * dummy mutex class, this - * of course does nothing. + * Destructor. Unlock the mutex. Since this is a dummy mutex + * class, this of course does nothing. */ ~ScopedLock () {} }; /** - * Simulate acquisition of the - * mutex. As this class does - * nothing really, this - * function does nothing as - * well. + * Simulate acquisition of the mutex. As this class does nothing + * really, this function does nothing as well. */ inline void acquire () const {} /** - * Simulate release of the - * mutex. As this class does - * nothing really, this - * function does nothing as - * well. + * Simulate release of the mutex. As this class does nothing + * really, this function does nothing as well. */ inline void release () const {} }; @@ -155,15 +129,15 @@ namespace Threads /** * This class is used in single threaded mode instead of a class - * implementing real condition variable semantics. It allows to write - * programs such that they start new threads and/or lock objects in - * multithreading mode, and use dummy thread management and - * synchronisation classes instead when running in single-thread - * mode. Specifically, the new_thread() functions only call the function - * but wait for it to return instead of running in on another thread, - * and the mutices do nothing really. The only reason to provide such - * a function is that the program can be compiled both in MT and - * non-MT mode without difference. + * implementing real condition variable semantics. It allows to + * write programs such that they start new threads and/or lock + * objects in multithreading mode, and use dummy thread management + * and synchronisation classes instead when running in single-thread + * mode. Specifically, the new_thread() functions only call the + * function but wait for it to return instead of running in on + * another thread, and the mutices do nothing really. The only + * reason to provide such a function is that the program can be + * compiled both in MT and non-MT mode without difference. * * In this particular case, just as with mutexes, the functions do * nothing, and by this provide the same semantics of condition @@ -175,40 +149,26 @@ namespace Threads { public: /** - * Signal to a single listener - * that a condition has been - * met, i.e. that some data - * will now be available. Since - * in single threaded mode, - * this function of course does - * nothing. + * Signal to a single listener that a condition has been met, + * i.e. that some data will now be available. Since in single + * threaded mode, this function of course does nothing. */ inline void signal () const {} /** - * Signal to multiple listener - * that a condition has been - * met, i.e. that some data - * will now be available. Since - * in single threaded mode, - * this function of course does - * nothing. + * Signal to multiple listener that a condition has been met, + * i.e. that some data will now be available. Since in single + * threaded mode, this function of course does nothing. */ inline void broadcast () const {} /** - * Wait for the condition to be - * signalled. Signal variables - * need to be guarded by a - * mutex which needs to be - * given to this function as an - * argument, see the man page - * of posix_cond_wait for a - * description of the - * mechanisms. Since in single - * threaded mode, this function - * of course does nothing, but - * returns immediately. + * Wait for the condition to be signalled. Signal variables need + * to be guarded by a mutex which needs to be given to this + * function as an argument, see the man page of + * posix_cond_wait for a description of the + * mechanisms. Since in single threaded mode, this function of + * course does nothing, but returns immediately. */ inline void wait (DummyThreadMutex &) const {} }; @@ -217,16 +177,17 @@ namespace Threads /** * This class is used instead of a true barrier class when not using - * multithreading. It allows to write programs such that they use the - * same class names in multithreading and non-MT mode and thus may be - * compiled with or without thread-support without the need to use - * conditional compilation. Since a barrier class only makes sense in - * non-multithread mode if only one thread is to be synchronised - * (otherwise, the barrier could not be left, since the one thread is - * waiting for some other part of the program to reach a certain point - * of execution), the constructor of this class throws an exception if - * the count argument denoting the number of threads that need to - * be synchronized is not equal to one. + * multithreading. It allows to write programs such that they use + * the same class names in multithreading and non-MT mode and thus + * may be compiled with or without thread-support without the need + * to use conditional compilation. Since a barrier class only makes + * sense in non-multithread mode if only one thread is to be + * synchronised (otherwise, the barrier could not be left, since the + * one thread is waiting for some other part of the program to reach + * a certain point of execution), the constructor of this class + * throws an exception if the count argument denoting + * the number of threads that need to be synchronized is not equal + * to one. * * @author Wolfgang Bangerth, 2001 */ @@ -234,13 +195,9 @@ namespace Threads { public: /** - * Constructor. Since barriers - * are only useful in - * single-threaded mode if the - * number of threads to be - * synchronised is one, this - * constructor raises an - * exception if the count + * Constructor. Since barriers are only useful in single-threaded + * mode if the number of threads to be synchronised is one, this + * constructor raises an exception if the count * argument is one. */ DummyBarrier (const unsigned int count, @@ -248,11 +205,8 @@ namespace Threads void *arg = 0); /** - * Wait for all threads to - * reach this point. Since - * there may only be one - * thread, return immediately, - * i.e. this function is a + * Wait for all threads to reach this point. Since there may only + * be one thread, return immediately, i.e. this function is a * no-op. */ int wait () const @@ -261,8 +215,7 @@ namespace Threads } /** - * Dump the state of this - * object. Here: do nothing. + * Dump the state of this object. Here: do nothing. */ void dump () const {} @@ -284,30 +237,19 @@ namespace Threads #ifdef DEAL_II_WITH_THREADS /** - * Class implementing a - * Mutex. Mutexes are used to lock - * data structures to ensure that - * only a single thread of - * execution can access them at the - * same time. + * Class implementing a Mutex. Mutexes are used to lock data + * structures to ensure that only a single thread of execution can + * access them at the same time. * *

Copy semantics

* - * When copied, the receiving - * object does not receive any - * state from the object being - * copied, i.e. an entirely new - * mutex is created. This is - * consistent with expectations if - * a mutex is used as a member - * variable to lock the other - * member variables of a class: in - * that case, the mutex of the - * copied-to object should only - * guard the members of the - * copied-to object, not the - * members of both the copied-to - * and copied-from object. + * When copied, the receiving object does not receive any state from + * the object being copied, i.e. an entirely new mutex is + * created. This is consistent with expectations if a mutex is used + * as a member variable to lock the other member variables of a + * class: in that case, the mutex of the copied-to object should + * only guard the members of the copied-to object, not the members + * of both the copied-to and copied-from object. * * @author Wolfgang Bangerth, 2002, 2003, 2009 */ @@ -315,44 +257,26 @@ namespace Threads { public: /** - * Scoped lock class. When you - * declare an object of this - * type, you have to pass it a - * mutex, which is locked in - * the constructor of this - * class and unlocked in the - * destructor. The lock is thus - * held during the entire - * lifetime of this object, - * i.e. until the end of the - * present scope, which - * explains where the name - * comes from. This pattern of - * using locks with mutexes - * follows the - * resource-acquisition-is-initialization - * pattern, and was used first - * for mutexes by Doug - * Schmidt. It has the - * advantage that locking a - * mutex this way is - * thread-safe, i.e. when an - * exception is thrown between - * the locking and unlocking - * point, the destructor makes - * sure that the mutex is - * unlocked; this would not - * automatically be the case - * when you lock and unlock the - * mutex "by hand", i.e. using - * acquire() and release(). + * Scoped lock class. When you declare an object of this type, you + * have to pass it a mutex, which is locked in the constructor of + * this class and unlocked in the destructor. The lock is thus + * held during the entire lifetime of this object, i.e. until the + * end of the present scope, which explains where the name comes + * from. This pattern of using locks with mutexes follows the + * resource-acquisition-is-initialization pattern, and was used + * first for mutexes by Doug Schmidt. It has the advantage that + * locking a mutex this way is thread-safe, i.e. when an exception + * is thrown between the locking and unlocking point, the + * destructor makes sure that the mutex is unlocked; this would + * not automatically be the case when you lock and unlock the + * mutex "by hand", i.e. using acquire() and + * release(). */ class ScopedLock { public: /** - * Constructor. Lock the - * mutex. + * Constructor. Lock the mutex. */ ScopedLock (Mutex &m) : mutex(m) { @@ -360,10 +284,8 @@ namespace Threads } /** - * Destructor. Unlock the - * mutex. Since this is a - * dummy mutex class, this - * of course does nothing. + * Destructor. Unlock the mutex. Since this is a dummy mutex + * class, this of course does nothing. */ ~ScopedLock () { @@ -372,8 +294,7 @@ namespace Threads private: /** - * Store the address of the - * mutex object. + * Store the address of the mutex object. */ Mutex &mutex; }; @@ -385,11 +306,8 @@ namespace Threads {} /** - * Copy constructor. As - * discussed in this class's - * documentation, no state is - * copied from the object given - * as argument. + * Copy constructor. As discussed in this class's documentation, + * no state is copied from the object given as argument. */ Mutex (const Mutex &) : @@ -415,14 +333,12 @@ namespace Threads private: /** - * Data object storing the - * mutex data + * Data object storing the mutex data */ std_cxx11::mutex mutex; /** - * Make the class implementing - * condition variables a friend, since + * Make the class implementing condition variables a friend, since * it needs to access the mutex. */ friend class ConditionVariable; @@ -430,11 +346,9 @@ namespace Threads /** - * Class implementing a condition - * variable. The semantics of this - * class and its member functions - * are the same as those of the - * POSIX functions. + * Class implementing a condition variable. The semantics of this + * class and its member functions are the same as those of the POSIX + * functions. * * @author Wolfgang Bangerth, 2003 */ @@ -442,10 +356,8 @@ namespace Threads { public: /** - * Signal to a single listener - * that a condition has been - * met, i.e. that some data - * will now be available. + * Signal to a single listener that a condition has been met, + * i.e. that some data will now be available. */ inline void signal () { @@ -453,10 +365,8 @@ namespace Threads } /** - * Signal to multiple listener - * that a condition has been - * met, i.e. that some data - * will now be available. + * Signal to multiple listener that a condition has been met, + * i.e. that some data will now be available. */ inline void broadcast () { @@ -464,18 +374,13 @@ namespace Threads } /** - * Wait for the condition to be - * signalled. Signal variables - * need to be guarded by a - * mutex which needs to be - * given to this function as an - * argument, see the man page - * of pthread_cond_wait for a - * description of the + * Wait for the condition to be signalled. Signal variables need + * to be guarded by a mutex which needs to be given to this + * function as an argument, see the man page of + * pthread_cond_wait for a description of the * mechanisms. * - * The mutex is assumed held at the - * entry to this function but is + * The mutex is assumed held at the entry to this function but is * released upon exit. */ inline void wait (Mutex &mutex) @@ -487,38 +392,25 @@ namespace Threads private: /** - * Data object storing the - * necessary data. + * Data object storing the necessary data. */ std_cxx11::condition_variable condition_variable; }; /** - * Implementation of a thread - * barrier class, based on the - * POSIX thread functions. POSIX - * barriers are a relatively new - * feature and are not supported on - * all systems. + * Implementation of a thread barrier class, based on the POSIX + * thread functions. POSIX barriers are a relatively new feature and + * are not supported on all systems. * - * If the configuration detected - * the absence of these functions, - * then barriers will not be - * available, and creating objects - * of this class will result in an - * exception been thrown unless the - * count given for the parties - * waiting for the barrier is equal - * to one (as in this case waiting - * for the barrier is a - * no-operation, and we can - * dispense with the POSIX - * functions at all). The rest of - * the threading functionality will - * be available in its full extent, - * though, even if POSIX barriers - * are not available. + * If the configuration detected the absence of these functions, + * then barriers will not be available, and creating objects of this + * class will result in an exception been thrown unless the count + * given for the parties waiting for the barrier is equal to one (as + * in this case waiting for the barrier is a no-operation, and we + * can dispense with the POSIX functions at all). The rest of the + * threading functionality will be available in its full extent, + * though, even if POSIX barriers are not available. * * @author Wolfgang Bangerth, 2002 */ @@ -526,8 +418,7 @@ namespace Threads { public: /** - * Constructor. Initialize the - * underlying POSIX barrier data + * Constructor. Initialize the underlying POSIX barrier data * structure. */ PosixThreadBarrier (const unsigned int count, @@ -535,30 +426,22 @@ namespace Threads void *arg = 0); /** - * Destructor. Release all - * resources. + * Destructor. Release all resources. */ ~PosixThreadBarrier (); /** - * Wait for all threads to - * reach this point. The return - * value is zero for all - * participating threads except - * for one, for which the - * return value is some - * non-zero value. The - * operating system picks the - * special thread by some not - * further known method. + * Wait for all threads to reach this point. The return value is + * zero for all participating threads except for one, for which + * the return value is some non-zero value. The operating system + * picks the special thread by some not further known method. */ int wait (); private: /** - * Data object storing the - * POSIX data which we need to - * call the POSIX functions. + * Data object storing the POSIX data which we need to call the + * POSIX functions. */ #ifndef DEAL_II_USE_MT_POSIX_NO_BARRIERS pthread_barrier_t barrier; @@ -569,66 +452,50 @@ namespace Threads /** - * Provide a backward compatible name (we - * used ThreadMutex up to release 6.1, but - * since it is already in a namespace - * Threads this seems redundant). + * Provide a backward compatible name (we used ThreadMutex up to + * release 6.1, but since it is already in a namespace Threads this + * seems redundant). * * @deprecated */ typedef Mutex ThreadMutex DEAL_II_DEPRECATED; /** - * Provide a backward compatible name (we - * used ThreadCondition up to release 6.1, - * but since it is already in a namespace - * Threads this seems redundant). + * Provide a backward compatible name (we used ThreadCondition up to + * release 6.1, but since it is already in a namespace Threads this + * seems redundant). * * @deprecated */ typedef ConditionVariable ThreadCondition DEAL_II_DEPRECATED; /** - * If using POSIX functions, then - * alias the POSIX wrapper classes - * to the names we use throughout - * the library. + * If using POSIX functions, then alias the POSIX wrapper classes to + * the names we use throughout the library. */ typedef PosixThreadBarrier Barrier; #else /** - * In non-multithread mode, the - * mutex and thread management - * classes are aliased to dummy - * classes that actually do - * nothing, in particular not lock - * objects. Likewise for the - * barrier class. + * In non-multithread mode, the mutex and thread management classes + * are aliased to dummy classes that actually do nothing, in + * particular not lock objects. Likewise for the barrier class. */ typedef DummyThreadMutex Mutex; typedef DummyThreadMutex ThreadMutex; /** - * In non-multithread mode, the - * mutex and thread management - * classes are aliased to dummy - * classes that actually do - * nothing, in particular not lock - * objects. Likewise for the - * barrier class. + * In non-multithread mode, the mutex and thread management classes + * are aliased to dummy classes that actually do nothing, in + * particular not lock objects. Likewise for the barrier class. */ typedef DummyThreadCondition ConditionVariable; typedef DummyThreadCondition ThreadCondition; /** - * In non-multithread mode, the - * mutex and thread management - * classes are aliased to dummy - * classes that actually do - * nothing, in particular not lock - * objects. Likewise for the - * barrier class. + * In non-multithread mode, the mutex and thread management classes + * are aliased to dummy classes that actually do nothing, in + * particular not lock objects. Likewise for the barrier class. */ typedef DummyBarrier Barrier; #endif @@ -640,102 +507,64 @@ namespace Threads { /** - * Return the number of presently - * existing threads. This function - * may be useful in a situation - * where a large number of threads - * are concurrently, and you want - * to decide whether creation of - * another thread is reasonable or - * whether running the respective - * operation sequentially is more - * useful since already many more - * threads than processors are - * running. + * Return the number of presently existing threads. This function + * may be useful in a situation where a large number of threads are + * concurrently, and you want to decide whether creation of another + * thread is reasonable or whether running the respective operation + * sequentially is more useful since already many more threads than + * processors are running. * - * Note that the function returns - * the total number of threads, not - * those actually running. Some of - * the threads may be waiting for - * locks and mutexes, or may be - * sleeping until they are - * delivered with data to work on. + * Note that the function returns the total number of threads, not + * those actually running. Some of the threads may be waiting for + * locks and mutexes, or may be sleeping until they are delivered + * with data to work on. * - * Upon program start, this number - * is one. It is increased each - * time a thread is created using - * the Threads::new_thread - * function. It is decreased once - * a thread terminates by returning - * from the function that was - * spawned. + * Upon program start, this number is one. It is increased each time + * a thread is created using the Threads::new_thread function. It is + * decreased once a thread terminates by returning from the function + * that was spawned. * - * Note that this means that only - * threads created and terminated - * through the interfaces of this - * namespace are taken care of. If - * threads are created by directly - * calling the respective functions - * of the operating system - * (e.g. pthread_create - * for the POSIX thread interface), - * or if they are killed - * (e.g. either through - * pthread_exit from the - * spawned thread, or - * pthread_kill from - * another thread), then these - * events are not registered and - * counted for the result of this - * function. Likewise, threads that - * the Threading Building Blocks - * library may have created to work - * on tasks created using the - * Threads::new_task functions are - * not counted. + * Note that this means that only threads created and terminated + * through the interfaces of this namespace are taken care of. If + * threads are created by directly calling the respective functions + * of the operating system (e.g. pthread_create for the + * POSIX thread interface), or if they are killed (e.g. either + * through pthread_exit from the spawned thread, or + * pthread_kill from another thread), then these events + * are not registered and counted for the result of this + * function. Likewise, threads that the Threading Building Blocks + * library may have created to work on tasks created using the + * Threads::new_task functions are not counted. * * @ingroup threads */ unsigned int n_existing_threads (); /** - * Return a number used as id of - * this thread. This number is - * generated using the system call - * getpid, or, if it - * exists gettid. The - * result of either is converted to - * an integer and returned by this - * function. + * Return a number used as id of this thread. This number is + * generated using the system call getpid, or, if it + * exists gettid. The result of either is converted to + * an integer and returned by this function. * - * @todo As of now, none of our - * systems seems to support - * gettid, so that part of - * the code is untested yet. + * @todo As of now, none of our systems seems to support + * gettid, so that part of the code is untested yet. * * @ingroup threads */ unsigned int this_thread_id (); /** - * Split the range [begin,end) - * into n_intervals subintervals - * of equal size. The last interval - * will be a little bit larger, if - * the number of elements in the - * whole range is not exactly - * divisible by n_intervals. The - * type of the iterators has to - * fulfill the requirements of a - * forward iterator, - * i.e. operator++ must be - * available, and of course it must - * be assignable. + * Split the range [begin,end) into + * n_intervals subintervals of equal size. The last + * interval will be a little bit larger, if the number of elements + * in the whole range is not exactly divisible by + * n_intervals. The type of the iterators has to + * fulfill the requirements of a forward iterator, + * i.e. operator++ must be available, and of course it + * must be assignable. * - * A list of subintervals is - * returned as a vector of pairs of - * iterators, where each pair - * denotes the range + * A list of subintervals is returned as a vector of pairs of + * iterators, where each pair denotes the range * [begin[i],end[i]). * * @ingroup threads @@ -747,13 +576,10 @@ namespace Threads const unsigned int n_intervals); /** - * Split the interval [begin,end) - * into subintervals of (almost) - * equal size. This function works - * mostly as the one before, with - * the difference that instead of - * iterators, now values are taken - * that define the whole interval. + * Split the interval [begin,end) into subintervals of + * (almost) equal size. This function works mostly as the one + * before, with the difference that instead of iterators, now values + * are taken that define the whole interval. * * @ingroup threads */ @@ -767,12 +593,9 @@ namespace Threads */ /** - * A namespace in which helper - * functions and the like for the - * threading subsystem are - * implemented. The members of this - * namespace are not meant for - * public use. + * A namespace in which helper functions and the like for the + * threading subsystem are implemented. The members of this + * namespace are not meant for public use. * * @author Wolfgang Bangerth, 2003 */ @@ -780,66 +603,48 @@ namespace Threads { /** * @internal - * If in a sub-thread an - * exception is thrown, it is not - * propagated to the main - * thread. Therefore, the - * exception handler that is - * provided by the applications - * main function or some of its - * other parts will not be able - * to catch these - * exceptions. Therefore, we have - * to provide an exception - * handler in the top function of - * each sub-thread that at least - * catches the exception and - * prints some information, - * rather than letting the - * operating system to just kill - * the program without a - * message. In each of the - * functions we use as entry - * points to new threads, we - * therefore install a try-catch - * block, and if an exception of - * type std::exception is - * caught, it passes over control - * to this function, which will - * then provide some output. + * + * If in a sub-thread an exception is thrown, it is not + * propagated to the main thread. Therefore, the exception handler + * that is provided by the applications main function or some of + * its other parts will not be able to catch these + * exceptions. Therefore, we have to provide an exception handler + * in the top function of each sub-thread that at least catches + * the exception and prints some information, rather than letting + * the operating system to just kill the program without a + * message. In each of the functions we use as entry points to new + * threads, we therefore install a try-catch block, and if an + * exception of type std::exception is caught, it + * passes over control to this function, which will then provide + * some output. */ void handle_std_exception (const std::exception &exc); /** * @internal - * Same as above, but the type of - * the exception is not derived - * from std::exception, so - * there is little way to provide - * something more useful. + * + * Same as above, but the type of the exception is not + * derived from std::exception, so there is little + * way to provide something more useful. */ void handle_unknown_exception (); /** * @internal - * The following function is used - * for internal bookkeeping of the - * number of existing threads. It - * is not thought for use in - * application programs, but only - * for use in the template + * + * The following function is used for internal bookkeeping of the + * number of existing threads. It is not thought for use in + * application programs, but only for use in the template * functions below. */ void register_thread (); /** * @internal - * The following function is used - * for internal bookkeeping of the - * number of existing threads. It - * is not thought for use in - * application programs, but only - * for use in the template + * + * The following function is used for internal bookkeeping of the + * number of existing threads. It is not thought for use in + * application programs, but only for use in the template * functions below. */ void deregister_thread (); @@ -863,19 +668,15 @@ namespace Threads { typedef std::pair IteratorPair; - // in non-multithreaded mode, we - // often have the case that this - // function is called with - // n_intervals==1, so have a - // shortcut here to handle that - // case efficiently + // in non-multithreaded mode, we often have the case that this + // function is called with n_intervals==1, so have a shortcut here + // to handle that case efficiently if (n_intervals==1) return (std::vector (1, IteratorPair(begin, end))); - // if more than one interval - // requested, do the full work + // if more than one interval requested, do the full work const unsigned int n_elements = std::distance (begin, end); const unsigned int n_elements_per_interval = n_elements / n_intervals; const unsigned int residual = n_elements % n_intervals; @@ -888,20 +689,14 @@ namespace Threads if (i != n_intervals-1) { return_values[i].second = return_values[i].first; - // note: the cast is - // performed to avoid a - // warning of gcc that in - // the library `dist>=0' - // is checked (dist has a - // template type, which - // here is unsigned if no - // cast is performed) + // note: the cast is performed to avoid a warning of gcc + // that in the library `dist>=0' is checked (dist has a + // template type, which here is unsigned if no cast is + // performed) std::advance (return_values[i].second, static_cast(n_elements_per_interval)); - // distribute residual in - // division equally among - // the first few - // subintervals + // distribute residual in division equally among the first + // few subintervals if (i < residual) ++return_values[i].second; @@ -922,12 +717,10 @@ namespace Threads { /** * @internal - * Given an arbitrary type RT, - * store an element of it and grant - * access to it through functions - * get() and set(). There are - * specializations for reference - * types (which cannot be set), and + * + * Given an arbitrary type RT, store an element of it and grant + * access to it through functions get() and set(). There are + * specializations for reference types (which cannot be set), and * for type void. */ template struct return_value @@ -941,6 +734,7 @@ namespace Threads { return value; } + inline void set (RT v) { value = v; @@ -950,16 +744,12 @@ namespace Threads /** * @internal - * Given an arbitrary type RT, - * store an element of it and grant - * access to it through functions - * get() and set(). This is the - * specialization for reference - * types: since they cannot be set - * after construction time, we - * store a pointer instead, that - * holds the address of the object - * being referenced. + * + * Given an arbitrary type RT, store an element of it and grant + * access to it through functions get() and set(). This is the + * specialization for reference types: since they cannot be set + * after construction time, we store a pointer instead, that holds + * the address of the object being referenced. */ template struct return_value { @@ -981,14 +771,11 @@ namespace Threads /** * @internal - * Given an arbitrary type RT, - * store an element of it and grant - * access to it through functions - * get() and set(). This is the - * specialization for type void: - * there is obviously nothing to - * store, so no function set(), and - * a function get() that returns + * + * Given an arbitrary type RT, store an element of it and grant + * access to it through functions get() and set(). This is the + * specialization for type void: there is obviously nothing to + * store, so no function set(), and a function get() that returns * void. */ template <> struct return_value @@ -1022,16 +809,12 @@ namespace Threads { /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments, and whether the - * second argument is a const or - * non-const class, depending on - * which the member function will - * also me const or - * non-const. There are - * specializations of this class - * for each number of arguments. + * + * Construct a pointer to non-member function based on the + * template arguments, and whether the second argument is a const + * or non-const class, depending on which the member function will + * also me const or non-const. There are specializations of this + * class for each number of arguments. */ template ::value> @@ -1040,10 +823,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 0 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 0 arguments. */ template struct fun_ptr_helper @@ -1054,10 +836,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 1 argument. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 1 argument. */ template struct fun_ptr_helper @@ -1068,10 +849,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 2 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 2 arguments. */ template struct fun_ptr_helper @@ -1083,10 +863,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 3 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 3 arguments. */ template struct fun_ptr_helper @@ -1099,10 +878,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 4 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 4 arguments. */ template struct fun_ptr_helper @@ -1116,10 +894,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 5 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 5 arguments. */ template struct fun_ptr_helper @@ -1134,10 +911,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 6 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 6 arguments. */ template struct fun_ptr_helper @@ -1153,10 +929,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 7 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 7 arguments. */ template struct fun_ptr_helper @@ -1173,10 +948,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 8 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 8 arguments. */ template struct fun_ptr_helper @@ -1194,10 +968,9 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 9 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 9 arguments. */ template struct fun_ptr_helper @@ -1217,10 +990,10 @@ namespace Threads /** * @internal - * Construct a pointer to non-member - * function based on the template - * arguments. This is the - * specialization for 10 arguments. + * + * Construct a pointer to non-member function based on the + * template arguments. This is the specialization for 10 + * arguments. */ template struct fun_ptr_helper @@ -1241,20 +1014,15 @@ namespace Threads /** * @internal - * Construct a pointer to - * non-member function based on the - * template arguments. We do this - * by dispatching to the - * fun_ptr_helper classes that are - * overloaded on the number of + * + * Construct a pointer to non-member function based on the + * template arguments. We do this by dispatching to the + * fun_ptr_helper classes that are overloaded on the number of * elements. * - * Note that the last template - * argument for the - * fun_ptr_helper class is - * automatically computed in the - * default argument to the general - * template. + * Note that the last template argument for the fun_ptr_helper + * class is automatically computed in the default argument to the + * general template. */ template struct fun_ptr @@ -1270,95 +1038,67 @@ namespace Threads #ifdef DEAL_II_WITH_THREADS /** - * A class that represents threads. For - * each thread, we create exactly one of - * these objects -- exactly one because - * it carries the returned value of the - * function called on the thread. + * A class that represents threads. For each thread, we create + * exactly one of these objects -- exactly one because it carries + * the returned value of the function called on the thread. * - * While we have only one of these - * objects per thread, several - * Threads::Thread objects may refer to - * this descriptor. If all Thread - * objects go out of scope the - * ThreadDescriptor will detach from - * the thread before being destructed. + * While we have only one of these objects per thread, several + * Threads::Thread objects may refer to this descriptor. If all + * Thread objects go out of scope the ThreadDescriptor will detach + * from the thread before being destructed. */ template struct ThreadDescriptor { /** - * An object that represents the - * thread started. + * An object that represents the thread started. */ std_cxx11::thread thread; /** - * An object that will hold the value - * returned by the function called on - * the thread. + * An object that will hold the value returned by the function + * called on the thread. * - * The return value is stored - * in a shared_ptr because we might - * abandon the the ThreadDescriptor. - * This makes sure the object stays - * alive until the thread exits. + * The return value is stored in a shared_ptr because we might + * abandon the the ThreadDescriptor. This makes sure the object + * stays alive until the thread exits. */ std_cxx11::shared_ptr > ret_val; /** - * A bool variable that is initially - * false, is set to true when a new - * thread is started, and is set back - * to false once join() has been - * called. + * A bool variable that is initially false, is set to true when + * a new thread is started, and is set back to false once join() + * has been called. * - * We use this variable to make sure - * we can call join() twice on the - * same thread. For some reason, the - * C++ standard library throws a - * std::system_error exception if one - * tries to call std::thread::join - * twice (and in fact, before the - * second call, std::thread::joinable - * returns false) but this is a - * somewhat desirable thing to do - * because one doesn't have to keep - * track whether join() has been - * called before. Using this - * variable, whenever we have called - * join() before, the variable is set - * to true and we can skip over - * calling std::thread::join() a - * second time. Access to this variable - * is guarded by the following mutex. + * We use this variable to make sure we can call join() twice on + * the same thread. For some reason, the C++ standard library + * throws a std::system_error exception if one tries to call + * std::thread::join twice (and in fact, before the second call, + * std::thread::joinable returns false) but this is a somewhat + * desirable thing to do because one doesn't have to keep track + * whether join() has been called before. Using this variable, + * whenever we have called join() before, the variable is set to + * true and we can skip over calling std::thread::join() a + * second time. Access to this variable is guarded by the + * following mutex. * - * @note Historically, we did not need the - * mutex for this variable: threads - * can only be joined from the thread - * that created it - * originally. Consequently, - * everything that happens in a - * function that does not create - * threads (such as the join() - * function below) looks atomic to - * the outside world. Since we clear - * and test thread_is_active in the - * same function as we call - * std::thread::join, these actions - * are atomic and need no mutex. Of - * course, two threads may call - * join() on the same thread object - * at the same time, but this action - * is undefined anyway since they can - * not both join the same thread. That said, - * more recent C++ standards do not appear to - * have the requirement any more that the only - * thread that can call join() is the one that - * created the thread. Neither does pthread_join - * appear to have this requirement any more. - * Consequently, we can in fact join from different - * threads and we test this in base/thread_validity_07. + * @note Historically, we did not need the mutex for this + * variable: threads can only be joined from the thread that + * created it originally. Consequently, everything that happens + * in a function that does not create threads (such as the + * join() function below) looks atomic to the outside + * world. Since we clear and test thread_is_active in the same + * function as we call std::thread::join, these actions are + * atomic and need no mutex. Of course, two threads may call + * join() on the same thread object at the same time, but this + * action is undefined anyway since they can not both join the + * same thread. That said, more recent C++ standards do not + * appear to have the requirement any more that the only thread + * that can call join() is the one that created the + * thread. Neither does pthread_join appear to have this + * requirement any more. Consequently, we can in fact join from + * different threads and we test this in + * base/thread_validity_07. */ bool thread_is_active; @@ -1384,9 +1124,8 @@ namespace Threads } /** - * Start the thread and let - * it put its return value - * into the ret_val object. + * Start the thread and let it put its return value into the + * ret_val object. */ void start (const std_cxx11::function &function) { @@ -1401,10 +1140,9 @@ namespace Threads */ void join () { - // see if the thread hasn't been - // joined yet. if it has, then - // join() is a no-op. use schmidt's double-checking - // strategy to use the mutex only when necessary + // see if the thread hasn't been joined yet. if it has, then + // join() is a no-op. use schmidt's double-checking strategy + // to use the mutex only when necessary if (thread_is_active == false) return; @@ -1420,25 +1158,17 @@ namespace Threads private: /** - * The function that runs on the - * thread. + * The function that runs on the thread. */ static void thread_entry_point (const std_cxx11::function function, std_cxx11::shared_ptr > ret_val) { - // call the function - // in question. since an - // exception that is - // thrown from one of the - // called functions will - // not propagate to the - // main thread, it will - // kill the program if - // not treated here - // before we return to - // the operating system's - // thread library + // call the function in question. since an exception that is + // thrown from one of the called functions will not propagate + // to the main thread, it will kill the program if not treated + // here before we return to the operating system's thread + // library internal::register_thread (); try { @@ -1458,31 +1188,25 @@ namespace Threads #else /** - * A class that represents threads. For - * each thread, we create exactly one of - * these objects -- exactly one because - * it carries the returned value of the - * function called on the thread. + * A class that represents threads. For each thread, we create + * exactly one of these objects -- exactly one because it carries + * the returned value of the function called on the thread. * - * While we have only one of these - * objects per thread, several - * Threads::Thread objects may refer to - * this descriptor. + * While we have only one of these objects per thread, several + * Threads::Thread objects may refer to this descriptor. */ template struct ThreadDescriptor { /** - * An object that will hold the value - * returned by the function called on - * the thread. + * An object that will hold the value returned by the function + * called on the thread. */ std_cxx11::shared_ptr > ret_val; /** - * Start the thread and - * let it put its return value into - * the ret_val object. + * Start the thread and let it put its return value into the + * ret_val object. */ void start (const std_cxx11::function &function) { @@ -1502,37 +1226,23 @@ namespace Threads /** - * An object that represents a - * spawned thread. This object can - * be freely copied around in user - * space, and all instances will - * represent the same thread and - * can require to wait for its - * termination and access its - * return value. + * An object that represents a spawned thread. This object can be + * freely copied around in user space, and all instances will + * represent the same thread and can require to wait for its + * termination and access its return value. * - * Threads can be abandoned, - * i.e. if you just call - * Threads::new_thread but don't - * care about the returned object, - * or if you assign the return - * Threads::Thread object to an - * object that subsequently goes - * out of scope, then the thread - * previously created will still - * continue to do work. You will - * simply not be able to access its - * return value any more, and it - * may also happen that your - * program terminates before the - * thread has finished its work. + * Threads can be abandoned, i.e. if you just call + * Threads::new_thread but don't care about the returned object, or + * if you assign the return Threads::Thread object to an object that + * subsequently goes out of scope, then the thread previously + * created will still continue to do work. You will simply not be + * able to access its return value any more, and it may also happen + * that your program terminates before the thread has finished its + * work. * - * The default value of the - * template argument is void, - * so if the function you are - * calling on a new thread has no - * return value, you can omit the - * template argument. + * The default value of the template argument is void, + * so if the function you are calling on a new thread has no return + * value, you can omit the template argument. * * @author Wolfgang Bangerth, 2003, 2009 * @ingroup threads @@ -1543,26 +1253,20 @@ namespace Threads { public: /** - * Construct a thread object - * with a function object. + * Construct a thread object with a function object. */ Thread (const std_cxx11::function &function) : thread_descriptor (new internal::ThreadDescriptor()) { - // in a second step, start - // the thread. + // in a second step, start the thread. thread_descriptor->start (function); } /** - * Default constructor. You - * can't do much with a thread - * object constructed this way, - * except for assigning it a - * thread object that holds - * data created by the - * new_thread() functions. + * Default constructor. You can't do much with a thread object + * constructed this way, except for assigning it a thread object + * that holds data created by the new_thread() functions. */ Thread () {} @@ -1575,12 +1279,10 @@ namespace Threads {} /** - * Join the thread represented by this - * object, i.e. wait for it to - * finish. If you have used the default - * constructor of this class and have - * not assigned a thread object to it, - * then this function is a no-op. + * Join the thread represented by this object, i.e. wait for it to + * finish. If you have used the default constructor of this class + * and have not assigned a thread object to it, then this function + * is a no-op. */ void join () const { @@ -1589,11 +1291,8 @@ namespace Threads } /** - * Get the return value of the - * function of the - * thread. Since this is only - * available once the thread - * finishes, this implicitly + * Get the return value of the function of the thread. Since this + * is only available once the thread finishes, this implicitly * also calls join(). */ RT return_value () @@ -1603,11 +1302,8 @@ namespace Threads } /** - * Return true if this object - * has had a thread associated - * with it, either by using the - * non-default constructor or - * by assignment. + * Return true if this object has had a thread associated with it, + * either by using the non-default constructor or by assignment. */ bool valid () const { @@ -1616,13 +1312,10 @@ namespace Threads /** - * Check for equality of thread - * objects. Since objects of - * this class store an implicit - * pointer to an object that - * exists exactly once for each - * thread, the check is simply - * to compare these pointers. + * Check for equality of thread objects. Since objects of this + * class store an implicit pointer to an object that exists + * exactly once for each thread, the check is simply to compare + * these pointers. */ bool operator == (const Thread &t) { @@ -1631,15 +1324,10 @@ namespace Threads private: /** - * Shared pointer to the object - * representing the thread, and - * abstracting operating system - * functions to work on - * it. Boost's shared pointer - * implementation will make - * sure that that object lives - * as long as there is at least - * one subscriber to it. + * Shared pointer to the object representing the thread, and + * abstracting operating system functions to work on it. Boost's + * shared pointer implementation will make sure that that object + * lives as long as there is at least one subscriber to it. */ std_cxx11::shared_ptr > thread_descriptor; }; @@ -1648,13 +1336,11 @@ namespace Threads namespace internal { /** - * A general template that returns - * std_cxx11::ref(t) if t is of reference - * type, and t otherwise. + * A general template that returns std_cxx11::ref(t) if t is of + * reference type, and t otherwise. * - * The case that t is of reference type - * is handled in a partial specialization - * declared below. + * The case that t is of reference type is handled in a partial + * specialization declared below. */ template struct maybe_make_ref @@ -1668,12 +1354,10 @@ namespace Threads /** - * A general template that returns - * std_cxx11::ref(t) if t is of reference - * type, and t otherwise. + * A general template that returns std_cxx11::ref(t) if t is of + * reference type, and t otherwise. * - * The case that t is of reference type - * is handled in this partial + * The case that t is of reference type is handled in this partial * specialization. */ template @@ -1692,27 +1376,18 @@ namespace Threads { /** * @internal - * General template declaration - * of a class that is used to - * encapsulate arguments to - * global and static member - * functions, make sure a new - * thread is created and that - * function being run on that - * thread. * - * Although this general template - * is not implemented at all, the - * default template argument - * makes sure that whenever using - * the name of this class, the - * last template argument will be - * computed correctly from the - * previous arguments, and the - * correct specialization for - * this last template argument be - * used, even though we need to - * specify it. + * General template declaration of a class that is used to + * encapsulate arguments to global and static member functions, + * make sure a new thread is created and that function being run + * on that thread. + * + * Although this general template is not implemented at all, the + * default template argument makes sure that whenever using the + * name of this class, the last template argument will be computed + * correctly from the previous arguments, and the correct + * specialization for this last template argument be used, even + * though we need to specify it. */ template class fun_encapsulator; @@ -1722,8 +1397,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with no arguments. + * + * Encapsulator class for functions with no arguments. */ template class fun_encapsulator @@ -1750,8 +1425,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 1 argument. + * + * Encapsulator class for functions with 1 argument. */ template class fun_encapsulator @@ -1781,8 +1456,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 2 arguments. + * + * Encapsulator class for functions with 2 arguments. */ template class fun_encapsulator @@ -1814,8 +1489,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 3 arguments. + * + * Encapsulator class for functions with 3 arguments. */ template class fun_encapsulator @@ -1849,8 +1524,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 4 arguments. + * + * Encapsulator class for functions with 4 arguments. */ template class fun_encapsulator @@ -1886,8 +1561,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 5 arguments. + * + * Encapsulator class for functions with 5 arguments. */ template class fun_encapsulator @@ -1925,8 +1600,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 6 arguments. + * + * Encapsulator class for functions with 6 arguments. */ template class fun_encapsulator @@ -1966,8 +1641,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 7 arguments. + * + * Encapsulator class for functions with 7 arguments. */ template class fun_encapsulator @@ -2009,8 +1684,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 8 arguments. + * + * Encapsulator class for functions with 8 arguments. */ template class fun_encapsulator @@ -2054,8 +1729,8 @@ namespace Threads /** * @internal - * Encapsulator class for - * functions with 9 arguments. + * + * Encapsulator class for functions with 9 arguments. */ template class fun_encapsulator @@ -2106,8 +1781,7 @@ namespace Threads // ----------- encapsulators for functions not taking any parameters /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with no arguments. * * @deprecated Use new_thread() instead. @@ -2128,9 +1802,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * no arguments. + * Overload of the non-const spawn function for member functions + * with no arguments. * * @deprecated Use new_thread() instead. */ @@ -2151,8 +1824,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with no + * Overload of the spawn function for const member functions with no * arguments. * * @deprecated Use new_thread() instead. @@ -2179,8 +1851,7 @@ namespace Threads // ----------- encapsulators for unary functions /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 1 argument. * * @deprecated Use new_thread() instead. @@ -2202,9 +1873,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 1 argument. + * Overload of the non-const spawn function for member functions + * with 1 argument. * * @deprecated Use new_thread() instead. */ @@ -2225,8 +1895,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 1 + * Overload of the spawn function for const member functions with 1 * argument. * * @deprecated Use new_thread() instead. @@ -2251,8 +1920,7 @@ namespace Threads // ----------- encapsulators for binary functions /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 2 arguments. * * @deprecated Use new_thread() instead. @@ -2274,9 +1942,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 2 arguments. + * Overload of the non-const spawn function for member functions + * with 2 arguments. * * @deprecated Use new_thread() instead. */ @@ -2297,8 +1964,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 2 + * Overload of the spawn function for const member functions with 2 * arguments. * * @deprecated Use new_thread() instead. @@ -2323,8 +1989,7 @@ namespace Threads // ----------- encapsulators for ternary functions /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 3 arguments. * * @deprecated Use new_thread() instead. @@ -2348,9 +2013,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 3 arguments. + * Overload of the non-const spawn function for member functions + * with 3 arguments. * * @deprecated Use new_thread() instead. */ @@ -2373,8 +2037,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 3 + * Overload of the spawn function for const member functions with 3 * arguments. * * @deprecated Use new_thread() instead. @@ -2402,8 +2065,7 @@ namespace Threads // ----------- encapsulators for functions with 4 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 4 arguments. * * @deprecated Use new_thread() instead. @@ -2427,9 +2089,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 4 arguments. + * Overload of the non-const spawn function for member functions + * with 4 arguments. * * @deprecated Use new_thread() instead. */ @@ -2452,8 +2113,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 4 + * Overload of the spawn function for const member functions with 4 * arguments. * * @deprecated Use new_thread() instead. @@ -2480,8 +2140,7 @@ namespace Threads // ----------- encapsulators for functions with 5 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 5 arguments. * * @deprecated Use new_thread() instead. @@ -2507,9 +2166,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 5 arguments. + * Overload of the non-const spawn function for member functions + * with 5 arguments. * * @deprecated Use new_thread() instead. */ @@ -2534,8 +2192,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 5 + * Overload of the spawn function for const member functions with 5 * arguments. * * @deprecated Use new_thread() instead. @@ -2564,8 +2221,7 @@ namespace Threads // ----------- encapsulators for functions with 6 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 6 arguments. * * @deprecated Use new_thread() instead. @@ -2591,9 +2247,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 6 arguments. + * Overload of the non-const spawn function for member functions + * with 6 arguments. * * @deprecated Use new_thread() instead. */ @@ -2618,8 +2273,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 6 + * Overload of the spawn function for const member functions with 6 * arguments. * * @deprecated Use new_thread() instead. @@ -2650,8 +2304,7 @@ namespace Threads // ----------- encapsulators for functions with 7 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 7 arguments. * * @deprecated Use new_thread() instead. @@ -2681,9 +2334,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 7 arguments. + * Overload of the non-const spawn function for member functions + * with 7 arguments. * * @deprecated Use new_thread() instead. */ @@ -2712,8 +2364,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 7 + * Overload of the spawn function for const member functions with 7 * arguments. * * @deprecated Use new_thread() instead. @@ -2748,8 +2399,7 @@ namespace Threads // ----------- encapsulators for functions with 8 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 8 arguments. * * @deprecated Use new_thread() instead. @@ -2783,9 +2433,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 8 arguments. + * Overload of the non-const spawn function for member functions + * with 8 arguments. * * @deprecated Use new_thread() instead. */ @@ -2818,8 +2467,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 8 + * Overload of the spawn function for const member functions with 8 * arguments. * * @deprecated Use new_thread() instead. @@ -2858,8 +2506,7 @@ namespace Threads // ----------- encapsulators for functions with 9 arguments /** - * Overload of the spawn function for - * non-member or static member + * Overload of the spawn function for non-member or static member * functions with 9 arguments. * * @deprecated Use new_thread() instead. @@ -2893,9 +2540,8 @@ namespace Threads /** - * Overload of the non-const spawn - * function for member functions with - * 9 arguments. + * Overload of the non-const spawn function for member functions + * with 9 arguments. * * @deprecated Use new_thread() instead. */ @@ -2928,8 +2574,7 @@ namespace Threads } /** - * Overload of the spawn function for - * const member functions with 9 + * Overload of the spawn function for const member functions with 9 * arguments. * * @deprecated Use new_thread() instead. @@ -2969,11 +2614,9 @@ namespace Threads // ----------- thread starters for functions not taking any parameters /** - * Overload of the new_thread function for - * objects that can be converted to - * std_cxx11::function, i.e. anything - * that can be called like a function - * object without arguments and returning + * Overload of the new_thread function for objects that can be + * converted to std_cxx11::function, i.e. anything that can + * be called like a function object without arguments and returning * an object of type RT (or void). * * @ingroup threads @@ -2987,9 +2630,8 @@ namespace Threads } /** - * Overload of the new_thread function for - * non-member or static member - * functions with no arguments. + * Overload of the new_thread function for non-member or static + * member functions with no arguments. * * @ingroup threads */ @@ -3003,9 +2645,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * no arguments. + * Overload of the non-const new_thread function for member + * functions with no arguments. * * @ingroup threads */ @@ -3023,9 +2664,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with no - * arguments. + * Overload of the new_thread function for const member functions + * with no arguments. * * @ingroup threads */ @@ -3046,9 +2686,8 @@ namespace Threads // ----------- thread starters for unary functions /** - * Overload of the new_thread function for - * non-member or static member - * functions with 1 argument. + * Overload of the new_thread function for non-member or static + * member functions with 1 argument. * * @ingroup threads */ @@ -3067,9 +2706,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 1 argument. + * Overload of the non-const new_thread function for member + * functions with 1 argument. * * @ingroup threads */ @@ -3088,9 +2726,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 1 - * argument. + * Overload of the new_thread function for const member functions + * with 1 argument. * * @ingroup threads */ @@ -3111,9 +2748,8 @@ namespace Threads // ----------- thread starters for binary functions /** - * Overload of the new_thread function for - * non-member or static member - * functions with 2 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 2 arguments. * * @ingroup threads */ @@ -3134,9 +2770,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 2 arguments. + * Overload of the non-const new_thread function for member + * functions with 2 arguments. * * @ingroup threads */ @@ -3157,9 +2792,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 2 - * arguments. + * Overload of the new_thread function for const member functions + * with 2 arguments. * * @ingroup threads */ @@ -3182,9 +2816,8 @@ namespace Threads // ----------- thread starters for ternary functions /** - * Overload of the new_thread function for - * non-member or static member - * functions with 3 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 3 arguments. * * @ingroup threads */ @@ -3208,9 +2841,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 3 arguments. + * Overload of the non-const new_thread function for member + * functions with 3 arguments. * * @ingroup threads */ @@ -3234,9 +2866,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 3 - * arguments. + * Overload of the new_thread function for const member functions + * with 3 arguments. * * @ingroup threads */ @@ -3263,9 +2894,8 @@ namespace Threads // ----------- thread starters for functions with 4 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 4 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 4 arguments. * * @ingroup threads */ @@ -3291,9 +2921,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 4 arguments. + * Overload of the non-const new_thread function for member + * functions with 4 arguments. * * @ingroup threads */ @@ -3319,9 +2948,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 4 - * arguments. + * Overload of the new_thread function for const member functions + * with 4 arguments. * * @ingroup threads */ @@ -3349,9 +2977,8 @@ namespace Threads // ----------- thread starters for functions with 5 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 5 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 5 arguments. * * @ingroup threads */ @@ -3380,9 +3007,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 5 arguments. + * Overload of the non-const new_thread function for member + * functions with 5 arguments. * * @ingroup threads */ @@ -3411,9 +3037,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 5 - * arguments. + * Overload of the new_thread function for const member functions + * with 5 arguments. * * @ingroup threads */ @@ -3444,9 +3069,8 @@ namespace Threads // ----------- thread starters for functions with 6 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 6 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 6 arguments. * * @ingroup threads */ @@ -3477,9 +3101,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 6 arguments. + * Overload of the non-const new_thread function for member + * functions with 6 arguments. * * @ingroup threads */ @@ -3510,9 +3133,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 6 - * arguments. + * Overload of the new_thread function for const member functions + * with 6 arguments. * * @ingroup threads */ @@ -3545,9 +3167,8 @@ namespace Threads // ----------- thread starters for functions with 7 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 7 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 7 arguments. * * @ingroup threads */ @@ -3581,9 +3202,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 7 arguments. + * Overload of the non-const new_thread function for member + * functions with 7 arguments. * * @ingroup threads */ @@ -3617,9 +3237,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 7 - * arguments. + * Overload of the new_thread function for const member functions + * with 7 arguments. * * @ingroup threads */ @@ -3655,9 +3274,8 @@ namespace Threads // ----------- thread starters for functions with 8 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 8 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 8 arguments. * * @ingroup threads */ @@ -3694,9 +3312,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 8 arguments. + * Overload of the non-const new_thread function for member + * functions with 8 arguments. * * @ingroup threads */ @@ -3733,9 +3350,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 8 - * arguments. + * Overload of the new_thread function for const member functions + * with 8 arguments. * * @ingroup threads */ @@ -3774,9 +3390,8 @@ namespace Threads // ----------- thread starters for functions with 9 arguments /** - * Overload of the new_thread function for - * non-member or static member - * functions with 9 arguments. + * Overload of the new_thread function for non-member or static + * member functions with 9 arguments. * * @ingroup threads */ @@ -3815,9 +3430,8 @@ namespace Threads /** - * Overload of the non-const new_thread - * function for member functions with - * 9 arguments. + * Overload of the non-const new_thread function for member + * functions with 9 arguments. * * @ingroup threads */ @@ -3856,9 +3470,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_thread function for - * const member functions with 9 - * arguments. + * Overload of the new_thread function for const member functions + * with 9 arguments. * * @ingroup threads */ @@ -3899,12 +3512,9 @@ namespace Threads // ------------------------ ThreadGroup ------------------------------------- /** - * A container for thread - * objects. Allows to add new - * thread objects and wait for them - * all together. The thread objects - * need to have the same return - * value for the called function. + * A container for thread objects. Allows to add new thread objects + * and wait for them all together. The thread objects need to have + * the same return value for the called function. * * @author Wolfgang Bangerth, 2003 * @ingroup threads @@ -3924,16 +3534,11 @@ namespace Threads } /** - * Wait for all threads in the - * collection to finish. It is - * not a problem if some of - * them have already been - * waited for, i.e. you may - * call this function more than - * once, and you can also add - * new thread objects between - * subsequent calls to this - * function if you want. + * Wait for all threads in the collection to finish. It is not a + * problem if some of them have already been waited for, i.e. you + * may call this function more than once, and you can also add new + * thread objects between subsequent calls to this function if you + * want. */ void join_all () const { @@ -3960,8 +3565,7 @@ namespace Threads template struct TaskDescriptor; /** - * The task class for TBB that is - * used by the TaskDescriptor + * The task class for TBB that is used by the TaskDescriptor * class. */ template @@ -3974,9 +3578,8 @@ namespace Threads virtual tbb::task *execute () { - // call the function object - // and put the return value - // into the proper place + // call the function object and put the return value into the + // proper place try { call (task_descriptor.function, task_descriptor.ret_val); @@ -3993,49 +3596,32 @@ namespace Threads } /** - * A reference to the descriptor - * object of this task. + * A reference to the descriptor object of this task. */ TaskDescriptor &task_descriptor; }; /** * @internal - * Base class describing a - * task. This is the basic - * class abstracting the - * Threading Building Blocks - * implementation of tasks. - * It provides a mechanism - * to start a new task, as well - * as for joining it. * - * Internally, the way things are - * implemented is that all Task<> - * objects keep a shared pointer - * to the task descriptor. When - * the last Task<> object goes - * out of scope, the destructor - * of the descriptor is - * called. Since tasks can not be - * abandoned, the destructor - * makes sure that the task is - * finished before it can - * continue to destroy the - * object. + * Base class describing a task. This is the basic class + * abstracting the Threading Building Blocks implementation of + * tasks. It provides a mechanism to start a new task, as well as + * for joining it. * - * Note that unlike threads, - * tasks are not always started - * right away, and so the - * starting thread can't rely on - * the fact that the started task - * can copy things off the - * spawning thread's stack - * frame. As a consequence, the - * task description needs to - * include a way to store the - * function and its arguments - * that shall be run on the task. + * Internally, the way things are implemented is that all Task<> + * objects keep a shared pointer to the task descriptor. When the + * last Task<> object goes out of scope, the destructor of the + * descriptor is called. Since tasks can not be abandoned, the + * destructor makes sure that the task is finished before it can + * continue to destroy the object. + * + * Note that unlike threads, tasks are not always started right + * away, and so the starting thread can't rely on the fact that + * the started task can copy things off the spawning thread's + * stack frame. As a consequence, the task description needs to + * include a way to store the function and its arguments that + * shall be run on the task. * * @author Wolfgang Bangerth, 2009 */ @@ -4044,66 +3630,52 @@ namespace Threads { private: /** - * The function and its arguments - * that are to be run on the task. + * The function and its arguments that are to be run on the + * task. */ std_cxx11::function function; /** - * Variable holding the data the TBB - * needs to work with a task. Set by - * the queue_up_task() function. Note - * that the object behind this - * pointer will be deleted upon - * termination of the task, so we do - * not have to do so ourselves. In - * particular, if all objects with - * pointers to this task_description - * object go out of scope then no - * action is needed on our behalf. + * Variable holding the data the TBB needs to work with a + * task. Set by the queue_up_task() function. Note that the + * object behind this pointer will be deleted upon termination + * of the task, so we do not have to do so ourselves. In + * particular, if all objects with pointers to this + * task_description object go out of scope then no action is + * needed on our behalf. */ tbb::task *task; /** - * A place where the task will - * deposit its return value. + * A place where the task will deposit its return value. */ return_value ret_val; /** - * A flag indicating whether the task - * has terminated. + * A flag indicating whether the task has terminated. */ bool task_is_done; public: /** - * Constructor. Take the function to - * be run on this task as argument. + * Constructor. Take the function to be run on this task as + * argument. */ TaskDescriptor (const std_cxx11::function &function); /** - * Default - * constructor. Throws an - * exception since we want to - * queue a task immediately - * upon construction of these - * objects to make sure that - * each TaskDescriptor object - * corresponds to exactly one - * task. + * Default constructor. Throws an exception since we want to + * queue a task immediately upon construction of these objects + * to make sure that each TaskDescriptor object corresponds to + * exactly one task. */ TaskDescriptor (); /** - * Copy constructor. Throws - * an exception since we want - * to make sure that each - * TaskDescriptor object - * corresponds to exactly one - * task. + * Copy constructor. Throws an exception since we want to make + * sure that each TaskDescriptor object corresponds to exactly + * one task. */ TaskDescriptor (const TaskDescriptor &); @@ -4113,28 +3685,17 @@ namespace Threads ~TaskDescriptor (); /** - * Queue up the task to the - * scheduler. We need to do - * this in a separate - * function since the new - * tasks needs to access - * objects from the current - * object and that can only - * reliably happen if the - * current object is - * completely constructed - * already. + * Queue up the task to the scheduler. We need to do this in a + * separate function since the new tasks needs to access objects + * from the current object and that can only reliably happen if + * the current object is completely constructed already. */ void queue_task (); /** - * Join a task, i.e. wait - * for it to finish. This - * function can safely be - * called from different - * threads at the same time, - * and can also be called - * more than once. + * Join a task, i.e. wait for it to finish. This function can + * safely be called from different threads at the same time, and + * can also be called more than once. */ void join (); @@ -4159,11 +3720,8 @@ namespace Threads void TaskDescriptor::queue_task () { - // use the pattern described in - // the TBB book on pages - // 230/231 ("Start a large task - // in parallel with the main - // program") + // use the pattern described in the TBB book on pages 230/231 + // ("Start a large task in parallel with the main program") task = new (tbb::task::allocate_root()) tbb::empty_task; task->set_ref_count (2); @@ -4193,28 +3751,19 @@ namespace Threads inline TaskDescriptor::~TaskDescriptor () { - // wait for the task to - // complete for sure + // wait for the task to complete for sure join (); - // now destroy the empty task - // structure. the book recommends to - // spawn it as well and let the - // scheduler destroy the object when - // done, but this has the disadvantage - // that the scheduler may not get to - // actually finishing the task before - // it goes out of scope (at the end of - // the program, or if a thread is done - // on which it was run) and then we - // would get a hard-to-decipher warning - // about unfinished tasks when the - // scheduler "goes out of the - // arena". rather, let's explicitly - // destroy the empty task - // object. before that, make sure that - // the task has been shut down, - // expressed by a zero reference count + // now destroy the empty task structure. the book recommends to + // spawn it as well and let the scheduler destroy the object + // when done, but this has the disadvantage that the scheduler + // may not get to actually finishing the task before it goes out + // of scope (at the end of the program, or if a thread is done + // on which it was run) and then we would get a hard-to-decipher + // warning about unfinished tasks when the scheduler "goes out + // of the arena". rather, let's explicitly destroy the empty + // task object. before that, make sure that the task has been + // shut down, expressed by a zero reference count Assert (task != 0, ExcInternalError()); Assert (task->ref_count()==0, ExcInternalError()); task->destroy (*task); @@ -4226,24 +3775,19 @@ namespace Threads void TaskDescriptor::join () { - // if the task is already done, just - // return. this makes sure we call - // tbb::Task::wait_for_all() exactly - // once, as required by TBB. we could - // also get the reference count of task - // for doing this, but that is usually - // slower. note that this does not work - // when the thread calling this - // function is not the same as the one - // that initialized the task. + // if the task is already done, just return. this makes sure we + // call tbb::Task::wait_for_all() exactly once, as required by + // TBB. we could also get the reference count of task for doing + // this, but that is usually slower. note that this does not + // work when the thread calling this function is not the same as + // the one that initialized the task. // - // TODO: can we assert that no other - // thread tries to end the task? + // TODO: can we assert that no other thread tries to end the + // task? if (task_is_done == true) return; - // let TBB wait for the task to - // complete. + // let TBB wait for the task to complete. task_is_done = true; task->wait_for_all(); } @@ -4253,26 +3797,20 @@ namespace Threads #else // no threading enabled /** - * A way to describe tasks. Since - * we are in non-MT mode at this - * place, things are a lot - * simpler than in MT mode. + * A way to describe tasks. Since we are in non-MT mode at this + * place, things are a lot simpler than in MT mode. */ template struct TaskDescriptor { /** - * A place where the task will - * deposit its return value. + * A place where the task will deposit its return value. */ return_value ret_val; /** - * Constructor. Call the - * given function and emplace - * the return value into the - * slot reserved for this - * purpose. + * Constructor. Call the given function and emplace the return + * value into the slot reserved for this purpose. */ TaskDescriptor (const std_cxx11::function &function) { @@ -4280,19 +3818,14 @@ namespace Threads } /** - * Wait for the task to - * return. Since we are in - * non-MT mode here, there is - * nothing to do. + * Wait for the task to return. Since we are in non-MT mode + * here, there is nothing to do. */ static void join () {} /** - * Run the task. Since we are - * here in non-MT mode, there - * is nothing to do that the - * constructor hasn't already - * done. + * Run the task. Since we are here in non-MT mode, there is + * nothing to do that the constructor hasn't already done. */ static void queue_task () {} }; @@ -4304,14 +3837,11 @@ namespace Threads /** - * Describes one task object based on the - * Threading Building Blocks' Task. Note - * that the call to join() must be executed - * on the same thread as the call to the - * constructor. Otherwise, there might be a - * deadlock. In other words, a Task - * object should never passed on to another - * task for calling the join() method. + * Describes one task object based on the Threading Building Blocks' + * Task. Note that the call to join() must be executed on the same + * thread as the call to the constructor. Otherwise, there might be + * a deadlock. In other words, a Task object should never passed on + * to another task for calling the join() method. * * @author Wolfgang Bangerth, 2009 * @ingroup threads @@ -4329,9 +3859,8 @@ namespace Threads */ Task (const std_cxx11::function &function_object) { - // create a task descriptor and tell it - // to queue itself up with the scheduling - // system + // create a task descriptor and tell it to queue itself up with + // the scheduling system task_descriptor = std_cxx11::shared_ptr > (new internal::TaskDescriptor(function_object)); @@ -4420,13 +3949,9 @@ namespace Threads /** - * Check for equality of task - * objects. Since objects of - * this class store an implicit - * pointer to an object that - * exists exactly once for each - * task, the check is simply - * to compare these pointers. + * Check for equality of task objects. Since objects of this class + * store an implicit pointer to an object that exists exactly once + * for each task, the check is simply to compare these pointers. */ bool operator == (const Task &t) { @@ -4444,12 +3969,9 @@ namespace Threads //@} private: /** - * Shared pointer to the object - * representing the task. Boost's - * shared pointer implementation will - * make sure that that object lives as - * long as there is at least one - * subscriber to it. + * Shared pointer to the object representing the task. Boost's + * shared pointer implementation will make sure that that object + * lives as long as there is at least one subscriber to it. */ std_cxx11::shared_ptr > task_descriptor; }; @@ -4457,11 +3979,9 @@ namespace Threads /** - * Overload of the new_task function for - * objects that can be converted to - * std_cxx11::function, i.e. anything - * that can be called like a function - * object without arguments and returning + * Overload of the new_task function for objects that can be + * converted to std_cxx11::function, i.e. anything that can + * be called like a function object without arguments and returning * an object of type RT (or void). * * @ingroup threads @@ -4475,8 +3995,7 @@ namespace Threads } /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with no arguments. * * @ingroup threads @@ -4491,9 +4010,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * no arguments. + * Overload of the non-const new_task function for member functions + * with no arguments. * * @ingroup threads */ @@ -4510,9 +4028,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with no - * arguments. + * Overload of the new_task function for const member functions with + * no arguments. * * @ingroup threads */ @@ -4533,8 +4050,7 @@ namespace Threads // ----------- thread starters for unary functions /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 1 argument. * * @ingroup threads @@ -4554,9 +4070,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 1 argument. + * Overload of the non-const new_task function for member functions + * with 1 argument. * * @ingroup threads */ @@ -4575,9 +4090,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 1 - * argument. + * Overload of the new_task function for const member functions with + * 1 argument. * * @ingroup threads */ @@ -4598,8 +4112,7 @@ namespace Threads // ----------- thread starters for binary functions /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 2 arguments. * * @ingroup threads @@ -4621,9 +4134,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 2 arguments. + * Overload of the non-const new_task function for member functions + * with 2 arguments. * * @ingroup threads */ @@ -4644,9 +4156,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 2 - * arguments. + * Overload of the new_task function for const member functions with + * 2 arguments. * * @ingroup threads */ @@ -4669,8 +4180,7 @@ namespace Threads // ----------- thread starters for ternary functions /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 3 arguments. * * @ingroup threads @@ -4695,9 +4205,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 3 arguments. + * Overload of the non-const new_task function for member functions + * with 3 arguments. * * @ingroup threads */ @@ -4721,9 +4230,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 3 - * arguments. + * Overload of the new_task function for const member functions with + * 3 arguments. * * @ingroup threads */ @@ -4750,8 +4258,7 @@ namespace Threads // ----------- thread starters for functions with 4 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 4 arguments. * * @ingroup threads @@ -4778,9 +4285,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 4 arguments. + * Overload of the non-const new_task function for member functions + * with 4 arguments. * * @ingroup threads */ @@ -4806,9 +4312,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 4 - * arguments. + * Overload of the new_task function for const member functions with + * 4 arguments. * * @ingroup threads */ @@ -4836,8 +4341,7 @@ namespace Threads // ----------- thread starters for functions with 5 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 5 arguments. * * @ingroup threads @@ -4867,9 +4371,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 5 arguments. + * Overload of the non-const new_task function for member functions + * with 5 arguments. * * @ingroup threads */ @@ -4898,9 +4401,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 5 - * arguments. + * Overload of the new_task function for const member functions with + * 5 arguments. * * @ingroup threads */ @@ -4931,8 +4433,7 @@ namespace Threads // ----------- thread starters for functions with 6 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 6 arguments. * * @ingroup threads @@ -4964,9 +4465,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 6 arguments. + * Overload of the non-const new_task function for member functions + * with 6 arguments. * * @ingroup threads */ @@ -4997,9 +4497,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 6 - * arguments. + * Overload of the new_task function for const member functions with + * 6 arguments. * * @ingroup threads */ @@ -5032,8 +4531,7 @@ namespace Threads // ----------- thread starters for functions with 7 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 7 arguments. * * @ingroup threads @@ -5068,9 +4566,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 7 arguments. + * Overload of the non-const new_task function for member functions + * with 7 arguments. * * @ingroup threads */ @@ -5104,9 +4601,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 7 - * arguments. + * Overload of the new_task function for const member functions with + * 7 arguments. * * @ingroup threads */ @@ -5142,8 +4638,7 @@ namespace Threads // ----------- thread starters for functions with 8 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 8 arguments. * * @ingroup threads @@ -5181,9 +4676,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 8 arguments. + * Overload of the non-const new_task function for member functions + * with 8 arguments. * * @ingroup threads */ @@ -5220,9 +4714,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 8 - * arguments. + * Overload of the new_task function for const member functions with + * 8 arguments. * * @ingroup threads */ @@ -5261,8 +4754,7 @@ namespace Threads // ----------- thread starters for functions with 9 arguments /** - * Overload of the new_task function for - * non-member or static member + * Overload of the new_task function for non-member or static member * functions with 9 arguments. * * @ingroup threads @@ -5302,9 +4794,8 @@ namespace Threads /** - * Overload of the non-const new_task - * function for member functions with - * 9 arguments. + * Overload of the non-const new_task function for member functions + * with 9 arguments. * * @ingroup threads */ @@ -5343,9 +4834,8 @@ namespace Threads #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG /** - * Overload of the new_task function for - * const member functions with 9 - * arguments. + * Overload of the new_task function for const member functions with + * 9 arguments. * * @ingroup threads */ @@ -5387,20 +4877,14 @@ namespace Threads // ------------------------ TaskGroup ------------------------------------- /** - * A container for task - * objects. Allows to add new - * task objects and wait for them - * all together. The task objects - * need to have the same return - * value for the called function. + * A container for task objects. Allows to add new task objects and + * wait for them all together. The task objects need to have the + * same return value for the called function. * - * Note that the call to join_all() must be - * executed on the same thread as the calls - * that add subtasks. Otherwise, there - * might be a deadlock. In other words, a - * Task object should never passed on to - * another task for calling the join() - * method. + * Note that the call to join_all() must be executed on the same + * thread as the calls that add subtasks. Otherwise, there might be + * a deadlock. In other words, a Task object should never passed on + * to another task for calling the join() method. * * @author Wolfgang Bangerth, 2003 * @ingroup tasks @@ -5420,16 +4904,11 @@ namespace Threads } /** - * Wait for all tasks in the - * collection to finish. It is - * not a problem if some of - * them have already been - * waited for, i.e. you may - * call this function more than - * once, and you can also add - * new task objects between - * subsequent calls to this - * function if you want. + * Wait for all tasks in the collection to finish. It is not a + * problem if some of them have already been waited for, i.e. you + * may call this function more than once, and you can also add new + * task objects between subsequent calls to this function if you + * want. */ void join_all () const {