prj/tech/libsrc/lg/thrdtool.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // $Source: x:/prj/tech/libsrc/lg/RCS/thrdtool.h $
   3 // $Author: TOML $
   4 // $Date: 1997/01/07 13:05:41 $
   5 // $Revision: 1.11 $
   6 //
   7 // Tools for thread synchronization and management.
   8 //
   9 //
  10
  11 #ifndef __THRDTOOL_H
  12 #define __THRDTOOL_H
  13
  14 #ifdef _WIN32
  15
  16 #if defined(DEBUG) || defined(ONEOPT)
  17 #define THRDTOOL_DEBUG
  18 #endif
  19
  20 ///////////////////////////////////////////////////////////////////////////////
  21 //
  22 // CLASS: cThreadLock
  23 //
  24 // Wrapper for critical sections management
  25 //
  26
  27 class cThreadLock
  28 {
  29 public:
  30     cThreadLock();
  31     ~cThreadLock();
  32
  33     //
  34     // Get/wait for ownership of the critical section
  35     //
  36     void Lock();
  37
  38     //
  39     // Release ownership of the critical section
  40     //
  41     void Unlock();
  42
  43     //
  44     // To make deadlocks easier to track it is useful to insert in
  45     // the code an assertion that says whether we own a critical
  46     // section or not.
  47     //
  48     BOOL AssertOwnedByCurrentThread();
  49
  50     //
  51     // In addition we provide a routine that allows usage of specific
  52     // critical sections to be traced.  This is NOT on by default.
  53     //
  54     void SetTrace(BOOL);
  55
  56
  57 private:
  58     // make copy constructor and assignment operator inaccessible
  59     cThreadLock(const cThreadLock &refCritSec);
  60     cThreadLock &operator=(const cThreadLock &refCritSec);
  61
  62     CRITICAL_SECTION m_CritSec;
  63
  64 #ifdef THRDTOOL_DEBUG
  65     DWORD   m_currentOwnerID;
  66     DWORD   m_lockCount;
  67     BOOL    m_fTrace;        // Trace this one
  68 #endif
  69 };
  70
  71
  72 ///////////////////////////////////////////////////////////////////////////////
  73 //
  74 // CLASS: cAutoLock
  75 //
  76 // Locks a critical section, and unlocks it automatically
  77 // when the lock goes out of scope
  78 //
  79
  80 class cAutoLock
  81 {
  82 public:
  83     cAutoLock(cThreadLock & lock);
  84     ~cAutoLock();
  85
  86 private:
  87     cThreadLock & m_lock;
  88
  89     // make copy constructor and assignment operator inaccessible
  90     cAutoLock(const cAutoLock &);
  91     cAutoLock &operator=(const cAutoLock &);
  92 };
  93
  94
  95 ///////////////////////////////////////////////////////////////////////////////
  96 //
  97 // CLASS: cThreadSyncObject
  98 //
  99 // Base class for event, semaphore and mutex objects.
 100 //
 101 // @TBD (toml 08-19-96): named objects? ability to "attach" an existing object?
 102 //
 103
 104 class cThreadSyncObject
 105 {
 106 public:
 107     ~cThreadSyncObject();
 108
 109     //
 110     // Query if object is useful
 111     //
 112     BOOL operator!() const;
 113
 114     //
 115     // Access handle
 116     //
 117     operator HANDLE ();
 118
 119     //
 120     // Wait for a signal from the object
 121     //
 122     BOOL Wait(DWORD dwTimeout = INFINITE);
 123
 124 protected:
 125     cThreadSyncObject();
 126     #ifdef THRDTOOL_DEBUG
 127     void AssertUseable();
 128     #endif
 129
 130     HANDLE m_hSyncObject;
 131
 132 private:
 133     // make copy constructor and assignment operator inaccessible
 134     cThreadSyncObject(const cThreadSyncObject &);
 135     cThreadSyncObject &operator=(const cThreadSyncObject &);
 136 };
 137
 138
 139 ///////////////////////////////////////////////////////////////////////////////
 140 //
 141 // CLASS: cThreadEvent
 142 //
 143 // Wrapper for unnamed event objects
 144 //
 145
 146 class cThreadEvent : public cThreadSyncObject
 147 {
 148 public:
 149     cThreadEvent(BOOL fManualReset = FALSE);
 150
 151     //
 152     // Set the state to signaled
 153     //
 154     BOOL Set();
 155
 156
 157     //
 158     // Set the state to nonsignaled
 159     //
 160     BOOL Reset();
 161
 162     //
 163     // A single operation that sets (to signaled) the state of
 164     // the object and then resets it (to nonsignaled) after
 165     // releasing the appropriate number of waiting threads.
 166     //
 167     BOOL Pulse();
 168
 169     //
 170     // Check if the event is signaled
 171     //
 172     BOOL Check();
 173
 174 private:
 175     // make copy constructor and assignment operator inaccessible
 176     cThreadEvent(const cThreadEvent &);
 177     cThreadEvent &operator=(const cThreadEvent &);
 178 };
 179
 180
 181 ///////////////////////////////////////////////////////////////////////////////
 182 //
 183 // CLASS: cThreadSemaphore
 184 //
 185
 186 class cThreadSemaphore : public cThreadSyncObject
 187 {
 188 public:
 189     cThreadSemaphore(long initialValue, long maxValue);
 190
 191     //
 192     // Increases the count of the semaphore object by a specified
 193     // amount.  Wait() decreases the count by one on return.
 194     //
 195     BOOL Release(long releaseCount = 1, long * pPreviousCount = NULL);
 196
 197 private:
 198     // make copy constructor and assignment operator inaccessible
 199     cThreadSemaphore(const cThreadSemaphore &);
 200     cThreadSemaphore &operator=(const cThreadSemaphore &);
 201 };
 202
 203
 204 ///////////////////////////////////////////////////////////////////////////////
 205 //
 206 // CLASS: cThreadMutex
 207 //
 208
 209 class cThreadMutex : public cThreadSyncObject
 210 {
 211 public:
 212     cThreadMutex(BOOL fEstablishInitialOwnership = FALSE);
 213
 214     //
 215     // Release ownership of the mutex
 216     //
 217     BOOL Release();
 218
 219 private:
 220     // make copy constructor and assignment operator inaccessible
 221     cThreadMutex(const cThreadMutex &);
 222     cThreadMutex &operator=(const cThreadMutex &);
 223 };
 224
 225 ///////////////////////////////////////////////////////////////////////////////
 226 //
 227 // CLASS: cWorkerThread
 228 //
 229 // Support for a worker thread
 230 //
 231 // Simple thread class supports creation of worker thread, synchronization
 232 // and simpler communication. Must derived to use.
 233 //
 234
 235 class cWorkerThread
 236 {
 237 public:
 238     cWorkerThread();
 239     virtual ~cWorkerThread();
 240
 241     ///////////////////////////////////
 242     //
 243     // Functions for the master thread
 244     //
 245
 246     //
 247     // Start thread running  - error if already running
 248     //
 249     BOOL Create();
 250
 251     //
 252     // Accessor thread calls this when done with thread (having told thread
 253     // to exit)
 254     //
 255     void WaitForClose(DWORD dwErrorTimeout = 10000);
 256
 257     //
 258     // Returns TRUE if thread has been created and hasn't yet exited
 259     //
 260     BOOL ThreadExists();
 261
 262
 263     ///////////////////////////////////
 264     //
 265     // Functions for both master and worker
 266     //
 267
 268     //
 269     // Get the priority
 270     //
 271     int GetPriority() const;
 272
 273     //
 274     // Set the priority
 275     //
 276     BOOL SetPriority(int);
 277
 278     //
 279     // Suspend a thread
 280     //
 281     DWORD Suspend();
 282
 283     //
 284     // Resume a suspended thread
 285     //
 286     DWORD Resume();
 287
 288     //
 289     // Force hard-termination of thread.  Used for critical failures.
 290     //
 291     BOOL Terminate(DWORD dwExitCode);
 292
 293
 294     ///////////////////////////////////
 295     //
 296     // Inter-thread communication
 297     //
 298     // Calls in either direction take place on the same "channel."
 299     // Seperate functions are specified to make indents obvious
 300     //
 301
 302     //
 303     // Master: Signal the thread, and block for a response
 304     //
 305     DWORD CallWorker(DWORD, BOOL fBoostWorkerPriorityToMaster = TRUE);
 306
 307     //
 308     // Master: Signal the thread, and block for a response
 309     //
 310     DWORD CallMaster(DWORD);
 311
 312     //
 313     // Wait for the next request
 314     //
 315     DWORD WaitForCall();
 316
 317     //
 318     // Is there a request?
 319     //
 320     BOOL PeekCall(DWORD * pParam = NULL);
 321
 322     //
 323     // Reply to the request
 324     //
 325     void Reply(DWORD);
 326
 327     //
 328     // If you want to do WaitForMultipleObjects you'll need to include
 329     // this handle in your wait list or you won't be responsive
 330     //
 331     HANDLE GetCallHandle();
 332
 333     //
 334     // Find out what the request was
 335     //
 336     DWORD GetCallParam() const;
 337
 338 protected:
 339
 340     enum
 341     {
 342         kInvalidCallParam = 0xffffffff
 343     };
 344
 345     //
 346     // Thread will run this function on startup
 347     // must be supplied by derived class
 348     //
 349     virtual DWORD ThreadProc() = 0;
 350
 351     cThreadLock m_Lock;
 352
 353 private:
 354
 355     DWORD Call(DWORD, BOOL fBoost);
 356
 357     //
 358     // Thread initially runs this. param is actually 'this'. function
 359     // just gets this and calls ThreadProc
 360     //
 361     static unsigned __stdcall InitialThreadProc(LPVOID pv);
 362
 363     // make copy constructor and assignment operator inaccessible
 364     cWorkerThread(const cWorkerThread &);
 365     cWorkerThread &operator=(const cWorkerThread &);
 366
 367     HANDLE          m_hThread;
 368
 369     cThreadEvent    m_EventSend;
 370     cThreadEvent    m_EventComplete;
 371
 372     DWORD           m_dwParam;
 373     DWORD           m_dwReturnVal;
 374
 375 };
 376
 377
 378 ///////////////////////////////////////////////////////////////////////////////
 379 //
 380 // Inline functions
 381 //
 382
 383 #ifndef THRDTOOL_DEBUG
 384
 385 ///////////////////////////////////////
 386 //
 387 // CLASS: cThreadLock
 388 //
 389
 390 inline cThreadLock::cThreadLock()
 391 {
 392     InitializeCriticalSection(&m_CritSec);
 393 }
 394
 395 ///////////////////////////////////////
 396
 397 inline cThreadLock::~cThreadLock()
 398 {
 399     DeleteCriticalSection(&m_CritSec);
 400 }
 401
 402 ///////////////////////////////////////
 403
 404 inline void cThreadLock::Lock()
 405 {
 406     EnterCriticalSection(&m_CritSec);
 407 }
 408
 409 ///////////////////////////////////////
 410
 411 inline void cThreadLock::Unlock()
 412 {
 413     LeaveCriticalSection(&m_CritSec);
 414 }
 415
 416 ///////////////////////////////////////
 417
 418 inline BOOL cThreadLock::AssertOwnedByCurrentThread()
 419 {
 420     return TRUE;
 421 }
 422
 423 ///////////////////////////////////////
 424
 425 inline void cThreadLock::SetTrace(BOOL)
 426 {
 427 }
 428
 429 #endif /* !THRDTOOL_DEBUG */
 430
 431 ///////////////////////////////////////
 432 //
 433 // CLASS: cAutoLock
 434 //
 435
 436 inline
 437 cAutoLock::cAutoLock(cThreadLock & lock)
 438   : m_lock(lock)
 439 {
 440     m_lock.Lock();
 441 }
 442
 443 ///////////////////////////////////////
 444
 445 inline
 446 cAutoLock::~cAutoLock()
 447 {
 448     m_lock.Unlock();
 449 }
 450
 451 ///////////////////////////////////////
 452 //
 453 // CLASS: cThreadSyncObject
 454 //
 455
 456 inline cThreadSyncObject::cThreadSyncObject()
 457   : m_hSyncObject(NULL)
 458 {
 459 }
 460
 461 ///////////////////////////////////////
 462
 463 inline cThreadSyncObject::~cThreadSyncObject()
 464 {
 465     if (m_hSyncObject)
 466         Verify(CloseHandle(m_hSyncObject));
 467 }
 468
 469 ///////////////////////////////////////
 470
 471 inline BOOL cThreadSyncObject::operator!() const
 472 {
 473     return !m_hSyncObject;
 474 }
 475
 476 ///////////////////////////////////////
 477
 478 #ifdef THRDTOOL_DEBUG
 479 inline void cThreadSyncObject::AssertUseable()
 480 {
 481     AssertMsg(m_hSyncObject, "Thread synchronization object is unuseable");
 482 }
 483 #endif
 484
 485 ///////////////////////////////////////
 486
 487 inline cThreadSyncObject::operator HANDLE ()
 488 {
 489     return m_hSyncObject;
 490 }
 491
 492 ///////////////////////////////////////
 493
 494 inline BOOL cThreadSyncObject::Wait(DWORD dwTimeout)
 495 {
 496 #ifdef THRDTOOL_DEBUG
 497     AssertUseable();
 498 #endif
 499     return (WaitForSingleObject(m_hSyncObject, dwTimeout) == WAIT_OBJECT_0);
 500 }
 501
 502 ///////////////////////////////////////
 503 //
 504 // CLASS: cThreadEvent
 505 //
 506
 507 inline BOOL cThreadEvent::Set()
 508 {
 509 #ifdef THRDTOOL_DEBUG
 510     AssertUseable();
 511 #endif
 512     return SetEvent(m_hSyncObject);
 513 }
 514
 515 ///////////////////////////////////////
 516
 517 inline BOOL cThreadEvent::Reset()
 518 {
 519 #ifdef THRDTOOL_DEBUG
 520     AssertUseable();
 521 #endif
 522     return ResetEvent(m_hSyncObject);
 523 }
 524
 525 ///////////////////////////////////////
 526
 527 inline BOOL cThreadEvent::Pulse()
 528 {
 529 #ifdef THRDTOOL_DEBUG
 530     AssertUseable();
 531 #endif
 532     return PulseEvent(m_hSyncObject);
 533 }
 534
 535 ///////////////////////////////////////
 536
 537 inline BOOL cThreadEvent::Check()
 538 {
 539 #ifdef THRDTOOL_DEBUG
 540     AssertUseable();
 541 #endif
 542     return Wait(0);
 543 }
 544
 545 ///////////////////////////////////////
 546 //
 547 // CLASS: cWorkerThread
 548 //
 549
 550 inline cWorkerThread::cWorkerThread()
 551   : m_EventSend(TRUE),                           // must be manual-reset for PeekCall()
 552     m_hThread(NULL)
 553 {
 554 }
 555
 556 ///////////////////////////////////////
 557
 558 inline int cWorkerThread::GetPriority() const
 559 {
 560     return GetThreadPriority(m_hThread);
 561 }
 562
 563 ///////////////////////////////////////
 564
 565 inline BOOL cWorkerThread::SetPriority(int priority)
 566 {
 567     return SetThreadPriority(m_hThread, priority);
 568 }
 569
 570 ///////////////////////////////////////
 571
 572 inline DWORD cWorkerThread::Suspend()
 573 {
 574     return SuspendThread(m_hThread);
 575 }
 576
 577 ///////////////////////////////////////
 578
 579 inline DWORD cWorkerThread::Resume()
 580 {
 581     return ResumeThread(m_hThread);
 582 }
 583
 584 ///////////////////////////////////////
 585
 586 inline BOOL cWorkerThread::Terminate(DWORD dwExitCode)
 587 {
 588     return TerminateThread(m_hThread, dwExitCode);
 589 }
 590
 591 ///////////////////////////////////////
 592
 593 inline DWORD cWorkerThread::CallWorker(DWORD dw, BOOL fBoostWorkerPriorityToMaster)
 594 {
 595     return Call(dw, fBoostWorkerPriorityToMaster);
 596 }
 597
 598 ///////////////////////////////////////
 599
 600 inline DWORD cWorkerThread::CallMaster(DWORD dw)
 601 {
 602     return Call(dw, FALSE);
 603 }
 604
 605 ///////////////////////////////////////
 606
 607 inline HANDLE cWorkerThread::GetCallHandle()
 608 {
 609     return m_EventSend;
 610 }
 611
 612 ///////////////////////////////////////
 613
 614 inline DWORD cWorkerThread::GetCallParam() const
 615 {
 616     return m_dwParam;
 617 }
 618
 619 ///////////////////////////////////////
 620
 621 #else
 622
 623 class cThreadLock
 624 {
 625 public:
 626     cThreadLock()   {};
 627     ~cThreadLock()  {};
 628     void Lock()     {};
 629     void Unlock()   {};
 630     BOOL AssertOwnedByCurrentThread() { return TRUE;}
 631     void SetTrace(BOOL) {};
 632 };
 633
 634 class cAutoLock
 635 {
 636 public:
 637     cAutoLock(cThreadLock & lock)   {};
 638     ~cAutoLock()                    {};
 639 };
 640
 641 #endif
 642
 643 ///////////////////////////////////////////////////////////////////////////////
 644
 645 #endif /* !__THRDTOOL_H */