PCL
Thread.h
Go to the documentation of this file.
1 // ____ ______ __
2 // / __ \ / ____// /
3 // / /_/ // / / /
4 // / ____// /___ / /___ PixInsight Class Library
5 // /_/ \____//_____/ PCL 2.7.0
6 // ----------------------------------------------------------------------------
7 // pcl/Thread.h - Released 2024-06-18T15:48:54Z
8 // ----------------------------------------------------------------------------
9 // This file is part of the PixInsight Class Library (PCL).
10 // PCL is a multiplatform C++ framework for development of PixInsight modules.
11 //
12 // Copyright (c) 2003-2024 Pleiades Astrophoto S.L. All Rights Reserved.
13 //
14 // Redistribution and use in both source and binary forms, with or without
15 // modification, is permitted provided that the following conditions are met:
16 //
17 // 1. All redistributions of source code must retain the above copyright
18 // notice, this list of conditions and the following disclaimer.
19 //
20 // 2. All redistributions in binary form must reproduce the above copyright
21 // notice, this list of conditions and the following disclaimer in the
22 // documentation and/or other materials provided with the distribution.
23 //
24 // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
25 // of their contributors, may be used to endorse or promote products derived
26 // from this software without specific prior written permission. For written
27 // permission, please contact info@pixinsight.com.
28 //
29 // 4. All products derived from this software, in any form whatsoever, must
30 // reproduce the following acknowledgment in the end-user documentation
31 // and/or other materials provided with the product:
32 //
33 // "This product is based on software from the PixInsight project, developed
34 // by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
35 //
36 // Alternatively, if that is where third-party acknowledgments normally
37 // appear, this acknowledgment must be reproduced in the product itself.
38 //
39 // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
40 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
41 // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
43 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
44 // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
45 // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
46 // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
47 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
49 // POSSIBILITY OF SUCH DAMAGE.
50 // ----------------------------------------------------------------------------
51 
52 #ifndef __PCL_Thread_h
53 #define __PCL_Thread_h
54 
56 
57 #include <pcl/Defs.h>
58 
59 #include <pcl/String.h>
60 #include <pcl/UIObject.h>
61 
62 namespace pcl
63 {
64 
65 // ----------------------------------------------------------------------------
66 
71 // ----------------------------------------------------------------------------
72 
99 namespace ThreadPriority
100 {
101  enum value_type
102  {
103  Inherit, // Inherit caller's thread priority.
104  Idle, // Schedule when no other threads are busy.
105  Lowest,
106  Low,
107  Normal, // Standard thread priority
108  High,
109  Highest,
110  TimeCritical, // Schedule as often as possible, taking precedence over any other threads.
111 #ifdef __PCL_WINDOWS
112  DefaultMax = Normal // On Windows, anything above Normal is the same as TimeCritical ...
113 #else
114  DefaultMax = Highest
115 #endif
116  };
117 }
118 
119 // ----------------------------------------------------------------------------
120 
129 class PCL_CLASS Thread : public UIObject
130 {
131 public:
132 
136  using priority = ThreadPriority::value_type;
137 
142 
146  ~Thread() override
147  {
148  }
149 
157  void EnsureUnique() override
158  {
159  // Threads are unique objects by definition.
160  }
161 
168  static Thread& Null();
169 
203  void Start( priority = ThreadPriority::Inherit, int processor = -1 );
204 
225 
250  bool SetAffinity( const Array<int>& processors );
251 
276  bool SetAffinity( int processor );
277 
290  void Kill(); // ### Dangerous - Use at your own risk! ###
291 
295  bool IsActive() const;
296 
300  priority Priority() const;
301 
305  void SetPriority( priority );
306 
312  {
313  SetPriority( ThreadPriority::Inherit );
314  }
315 
325  void Wait();
326 
342  bool Wait( unsigned ms );
343 
348  void Sleep( unsigned ms );
349 
350  /*
351  * Returns a reference to the current thread (the thread from which this
352  * member function is invoked), or Thread::Null() if the current thread is
353  * either (a) a thread not being controlled by the PixInsight API, or (b) a
354  * thread that has been created by another module.
355  static Thread& CurrentThread();
356  */
357 
369  static bool IsRootThread();
370 
379 
396  virtual void Run()
397  {
398  // Reimplement this function to provide your thread's functionality.
399  }
400 
418  uint32 Status() const;
419 
437  bool TryGetStatus( uint32& status ) const;
438 
453  void SetStatus( uint32 status );
454 
476  void Abort()
477  {
478  SetStatus( 0x80000000 );
479  }
480 
493  bool IsAborted() const
494  {
495  return (Status() & 0x80000000) != 0;
496  }
497 
509  bool TryIsAborted() const
510  {
511  uint32 status;
512  return TryGetStatus( status ) && (status & 0x80000000) != 0;
513  }
514 
530 
538  bool HasConsoleOutputText() const
539  {
540  return !ConsoleOutputText().IsEmpty();
541  }
542 
550 
564 
624  static int NumberOfThreads( size_type count, size_type overheadLimit = 1u );
625 
676  size_type overheadLimit = 1u,
677  int maxThreads = PCL_MAX_PROCESSORS );
678 
712  int align = 16,
713  size_type overheadLimit = 1u,
714  int maxThreads = PCL_MAX_PROCESSORS );
715 private:
716 
717  int m_processorIndex = -1;
718 
719  Thread( void* h ) : UIObject( h )
720  {
721  }
722 
723  void* CloneHandle() const override;
724 
725 protected:
726 
727  virtual bool IsStealth() const
728  {
729  return false;
730  }
731 
732  friend class ThreadDispatcher;
733 };
734 
735 // ----------------------------------------------------------------------------
736 
744 void PCL_FUNC Sleep( unsigned ms );
745 
746 // ----------------------------------------------------------------------------
747 
748 } // pcl
749 
750 #endif // __PCL_Thread_h
751 
752 // ----------------------------------------------------------------------------
753 // EOF pcl/Thread.h - Released 2024-06-18T15:48:54Z
Generic dynamic array.
Definition: Array.h:100
Unicode (UTF-16) string.
Definition: String.h:8113
Client-side interface to a PixInsight thread.
Definition: Thread.h:130
String ConsoleOutputText() const
bool IsAborted() const
Definition: Thread.h:493
static Array< size_type > OptimalThreadLoadsAligned(size_type count, int align=16, size_type overheadLimit=1u, int maxThreads=PCL_MAX_PROCESSORS)
uint32 Status() const
void ResetPriority()
Definition: Thread.h:311
static int NumberOfThreads(size_type count, size_type overheadLimit=1u)
bool TryIsAborted() const
Definition: Thread.h:509
void SetPriority(priority)
bool TryGetStatus(uint32 &status) const
bool IsActive() const
void FlushConsoleOutputText()
void ClearConsoleOutputText()
virtual void Run()
Definition: Thread.h:396
bool Wait(unsigned ms)
void EnsureUnique() override
Definition: Thread.h:157
static Thread & Null()
Array< int > Affinity() const
void Start(priority=ThreadPriority::Inherit, int processor=-1)
void SetStatus(uint32 status)
static bool IsRootThread()
priority Priority() const
bool HasConsoleOutputText() const
Definition: Thread.h:538
bool SetAffinity(int processor)
void Sleep(unsigned ms)
void Abort()
Definition: Thread.h:476
~Thread() override
Definition: Thread.h:146
static int NumberOfRunningThreads()
static Array< size_type > OptimalThreadLoads(size_type count, size_type overheadLimit=1u, int maxThreads=PCL_MAX_PROCESSORS)
bool SetAffinity(const Array< int > &processors)
Root base class for all user interface objects.
Definition: UIObject.h:95
unsigned int uint32
Definition: Defs.h:666
size_t size_type
Definition: Defs.h:609
void PCL_FUNC Sleep(unsigned ms)
PCL root namespace.
Definition: AbstractImage.h:77