src/OSspecific/POSIX/multiThreader/threadHandler.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | foam-extend: Open Source CFD
   4    \\    /   O peration     | Version:     3.2
   5     \\  /    A nd           | Web:         http://www.foam-extend.org
   6      \\/     M anipulation  | For copyright notice see file Copyright
   7 -------------------------------------------------------------------------------
   8 License
   9     This file is part of foam-extend.
  10
  11     foam-extend is free software: you can redistribute it and/or modify it
  12     under the terms of the GNU General Public License as published by the
  13     Free Software Foundation, either version 3 of the License, or (at your
  14     option) any later version.
  15
  16     foam-extend is distributed in the hope that it will be useful, but
  17     WITHOUT ANY WARRANTY; without even the implied warranty of
  18     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19     General Public License for more details.
  20
  21     You should have received a copy of the GNU General Public License
  22     along with foam-extend.  If not, see <http://www.gnu.org/licenses/>.
  23
  24 Class
  25     threadHandler
  26
  27 Description
  28     Helper class used to assist in multi-threading and synchronization.
  29
  30     Use this class to pass information to a threaded static member-function
  31     belonging to the class T.
  32
  33 Author
  34     Sandeep Menon
  35     University of Massachusetts Amherst
  36     All rights reserved
  37
  38 SourceFiles
  39     threadHandlerI.H
  40
  41 \*---------------------------------------------------------------------------*/
  42
  43 #ifndef threadHandler_H
  44 #define threadHandler_H
  45
  46 #include "FixedList.H"
  47 #include "List.H"
  48 #include "multiThreader.H"
  49
  50 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  51
  52 namespace Foam
  53 {
  54
  55 /*---------------------------------------------------------------------------*\
  56                            Class threadHandler Declaration
  57 \*---------------------------------------------------------------------------*/
  58
  59 template<class T>
  60 class threadHandler
  61 {
  62     // Reference to the template class
  63     T& tRef_;
  64
  65     // Reference to the multiThreader class
  66     const multiThreader& threader_;
  67
  68     // List of function argument pointers
  69     List<void *> argList_;
  70
  71     // Total number of threads
  72     const label nThreads_;
  73
  74     // ID generated by the pthreads API
  75     pthread_t pthreadID_;
  76
  77     // Is this a master/slave thread
  78     mutable bool master_;
  79
  80     // Synchronization mutexes
  81     mutable Mutex startMutex_;
  82     mutable Mutex stopMutex_;
  83
  84     // Conditionals for synchronization
  85     mutable Conditional startConditional_;
  86     mutable Conditional stopConditional_;
  87
  88     // On some implementations, a conditional wait
  89     // might return prematurely due to a spurious
  90     // wake-up signal. Use a predicate to avoid this
  91     // behaviour.
  92     mutable FixedList<bool, 2> predicate_;
  93
  94 public:
  95
  96     // Enumerants for signalling
  97     enum signalType
  98     {
  99         START,
 100         STOP
 101     };
 102
 103     // Constructor
 104     threadHandler
 105     (
 106         T& tPtr,
 107         const multiThreader& threader
 108     );
 109
 110     // Destructor
 111     ~threadHandler();
 112
 113     // Return a reference to the template class
 114     inline T& reference();
 115
 116     // Set a size for the argument list
 117     inline void setSize(const label size);
 118
 119     // Set a argument pointer for a particular index
 120     inline void set(const label index, void* argPtr);
 121
 122     // Return a reference to the multiThreader
 123     inline const multiThreader& threader() const;
 124
 125     // Return the number of threads
 126     inline label nThreads() const;
 127
 128     // Designate as master thread
 129     inline void setMaster() const;
 130
 131     // Designate as slave thread
 132     inline void setSlave() const;
 133
 134     // Is this a master thread?
 135     inline bool master() const;
 136
 137     // Is this a slave thread?
 138     inline bool slave() const;
 139
 140     // Lock this thread
 141     inline void lock(const signalType sType) const;
 142
 143     // Unlock this thread
 144     inline void unlock(const signalType sType) const;
 145
 146     // Send signal to a waiting conditional
 147     inline void sendSignal(const signalType sType) const;
 148
 149     // Wait for signal
 150     inline void waitForSignal(const signalType sType) const;
 151
 152     // Return state of the predicate variable
 153     inline bool predicate(const signalType sType) const;
 154
 155     // Set the predicate variable
 156     inline void setPredicate(const signalType sType) const;
 157
 158     // Unset the predicate variable
 159     inline void unsetPredicate(const signalType sType) const;
 160
 161     // Set the ID
 162     inline void setID(const pthread_t& pt);
 163
 164     // Return the ID
 165     inline pthread_t ID() const;
 166
 167     // Does the calling thread correspond to this handler?
 168     inline bool self() const;
 169
 170     // Return an argument pointer at a particular index
 171     inline void * operator()(const label index);
 172 };
 173
 174
 175 // Lock all threads provided by sequence
 176 template <class T>
 177 void lockThreads
 178 (
 179     const List<label>& sequence,
 180     const PtrList<threadHandler<T> >& handler
 181 );
 182
 183
 184 // Synchronize all threads provided by sequence
 185 template <class T>
 186 void synchronizeThreads
 187 (
 188     const List<label>& sequence,
 189     const PtrList<threadHandler<T> >& handler
 190 );
 191
 192
 193 // Execute threads for the submitted static function by sequence
 194 template <class T>
 195 void executeThreads
 196 (
 197     const List<label>& sequence,
 198     PtrList<threadHandler<T> >& handler,
 199     void (*tFunction)(void*)
 200 );
 201
 202 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 203
 204 } // End namespace Foam
 205
 206 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 207
 208 #include "threadHandlerI.H"
 209
 210 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 211
 212 #endif
 213
 214 // ************************************************************************* //