include/opencascade/OSD_Thread.hxx

0001 // Created on: 2006-03-10
0002 // Created by: data exchange team
0003 // Copyright (c) 2006-2014 OPEN CASCADE SAS
0004 //
0005 // This file is part of Open CASCADE Technology software library.
0006 //
0007 // This library is free software; you can redistribute it and/or modify it under
0008 // the terms of the GNU Lesser General Public License version 2.1 as published
0009 // by the Free Software Foundation, with special exception defined in the file
0010 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0011 // distribution for complete text of the license and disclaimer of any warranty.
0012 //
0013 // Alternatively, this file may be used under the terms of Open CASCADE
0014 // commercial license or contractual agreement.
0015
0016 #ifndef _OSD_Thread_HeaderFile
0017 #define _OSD_Thread_HeaderFile
0018
0019 #include <Standard.hxx>
0020 #include <Standard_DefineAlloc.hxx>
0021 #include <Standard_Handle.hxx>
0022
0023 #include <OSD_ThreadFunction.hxx>
0024 #include <OSD_PThread.hxx>
0025 #include <Standard_ThreadId.hxx>
0026 #include <Standard_Boolean.hxx>
0027
0028 //! A simple platform-intependent interface to execute
0029 //! and control threads.
0030 class OSD_Thread
0031 {
0032 public:
0033   DEFINE_STANDARD_ALLOC
0034
0035   //! Empty constructor
0036   Standard_EXPORT OSD_Thread();
0037
0038   //! Initialize the tool by the thread function
0039   //!
0040   //! Note: On Windows, you might have to take an address of the thread
0041   //! function explicitly to pass it to this constructor without compiler error
0042   Standard_EXPORT OSD_Thread(const OSD_ThreadFunction& func);
0043
0044   //! Copy constructor
0045   Standard_EXPORT OSD_Thread(const OSD_Thread& other);
0046
0047   //! Copy thread handle from other OSD_Thread object.
0048   Standard_EXPORT void Assign(const OSD_Thread& other);
0049
0050   void operator=(const OSD_Thread& other) { Assign(other); }
0051
0052   //! Destructor. Detaches the thread if it wasn't done already.
0053   Standard_EXPORT ~OSD_Thread();
0054
0055   Standard_EXPORT void SetPriority(const int thePriority);
0056
0057   //! Initialize the tool by the thread function.
0058   //! If the current thread handle is not null, nullifies it.
0059   //!
0060   //! Note: On Windows, you might have to take an address of the thread
0061   //! function explicitly to pass it to this method without compiler error
0062   Standard_EXPORT void SetFunction(const OSD_ThreadFunction& func);
0063
0064   //! Starts a thread with thread function given in constructor,
0065   //! passing the specified input data (as void *) to it.
0066   //! The parameter \a WNTStackSize (on Windows only)
0067   //! specifies size of the stack to be allocated for the thread
0068   //! (by default - the same as for the current executable).
0069   //! Returns True if thread started successfully
0070   Standard_EXPORT bool Run(void* const data = nullptr, const int WNTStackSize = 0);
0071
0072   //! Detaches the execution thread from this Thread object,
0073   //! so that it cannot be waited.
0074   //! Note that mechanics of this operation is different on
0075   //! UNIX/Linux (the thread is put to detached state) and Windows
0076   //! (the handle is closed).
0077   //! However, the purpose is the same: to instruct the system to
0078   //! release all thread data upon its completion.
0079   Standard_EXPORT void Detach();
0080
0081   //! Waits till the thread finishes execution.
0082   bool Wait()
0083   {
0084     void* aRes = nullptr;
0085     return Wait(aRes);
0086   }
0087
0088   //! Wait till the thread finishes execution.
0089   //! Returns True if wait was successful, False in case of error.
0090   //!
0091   //! If successful and \a result argument is provided, saves the pointer
0092   //! (void*) returned by the thread function in \a result.
0093   //!
0094   //! Note however that it is advisable not to rely upon returned result
0095   //! value, as it is not always the value actually returned by the thread
0096   //! function. In addition, on Windows it is converted via DWORD.
0097   Standard_EXPORT bool Wait(void*& theResult);
0098
0099   //! Waits for some time and if the thread is finished,
0100   //! it returns the result.
0101   //! The function returns false if the thread is not finished yet.
0102   Standard_EXPORT bool Wait(const int time, void*& theResult);
0103
0104   //! Returns ID of the currently controlled thread ID,
0105   //! or 0 if no thread is run
0106   Standard_EXPORT Standard_ThreadId GetId() const;
0107
0108   //! Auxiliary: returns ID of the current thread
0109   Standard_EXPORT static Standard_ThreadId Current();
0110
0111 private:
0112   OSD_ThreadFunction myFunc;
0113   OSD_PThread        myThread;
0114   Standard_ThreadId  myThreadId;
0115   int                myPriority;
0116 };
0117
0118 #endif // _OSD_Thread_HeaderFile