The IThread class represents threads of execution within the current program.
Use IThread objects to create or apply thread functions to threads which own graphical user interface (GUI) windows or process events for such windows. IThread serves an an anchor for thread specific information relating to GUI windows and the system objects relating to them. The derived class ICurrentThread provides additional functions which apply to the current thread.
If the thread you want to work with does not have any GUI windows, you can use the base class INonGUIThread instead of this class.
The versions of Motif and the X Toolkit supported by Open Class Library are not thread safe. To avoid problems due to this restriction, create and manage all of your graphical user interface (GUI) windows in a single thread. Do not start multiple threads of execution in which the GUI is initialized because this may cause undesirable interactions in the X Toolkit.
You can use INonGUIThread to create additional threads to perform tasks not requiring GUI windows.
Constructors & DestructorYou can construct, copy, assign, and destruct objects of this class.
![]() |
public:
virtual ~IThread()
Deallocates thread-related resources.
Note:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
IThread( SystemFnPtr function, unsigned long functionArgument, bool autoInitGUI = defaultAutoInitGUI ( ) )
Use this constructor to create an object of this class when you need to specify a function to run that you have defined using the _System calling convention. Such functions are typically started using the thread APIs that are defined for the operating system.
Use this form of the constructor to create a new object of this class and immediately dispatch it. This is equivalent to using the default constructor and then dispatching the thread using IThread::start.
This constructor permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| IInvalidRequest | The thread cannot be started; Win32s does not support multiple threads. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IThread(const IThread& thread)
Use this constructor if you would like to make a copy of an existing object of this class. This is commonly referred to as a copy constructor.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IThread( IThreadFn* threadFunction, bool autoInitGUI = defaultAutoInitGUI ( ) )
Use this constructor to start a thread when you need to specify a function to run in the new thread. You define this function by deriving a new class from the IThreadFn class. This constructor takes ownership of the derived IThreadFn object you provide so that Open Class Library can delete this object when the thread terminates.
Use this form of the constructor to create a new object of this class and immediately dispatch it. This is equivalent to using the default constructor and then dispatching the thread using IThread::start.
This constructor permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| IInvalidRequest | The thread cannot be started; Win32s does not support multiple threads. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IThread( OptlinkFnPtr function, void* functionArgument, bool autoInitGUI = defaultAutoInitGUI ( ) )
Use this constructor to create an object of this class when you need to specify a function to run that is defined with the _Optlink calling convention. Such functions are typically started using the function _beginThread.
Use this form of the constructor to create a new object of this class and immediately dispatch it. This is equivalent to using the default constructor and then dispatching the thread using IThread::start.
This constructor permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| IInvalidRequest | The thread cannot be started; Win32s does not support multiple threads. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IThread( const IThreadId& threadID, const IThreadHandle& threadHandle = IThreadHandle ( ) )
Use this constructor to create an object of this class from the thread identifier (ID) of a previously started thread. You can use this constructor to provide this class' functionality to threads created using alternate means (for example, the native operating system's system calls).
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
The threadHandle parameter is ignored.
The threadHandle parameter is ignored.
You must specify the threadHandle argument if the threadId argument does not refer to the current thread. You can use the return value of the CreateThread API for the thread handle.
public:
IThread()
Use this, the default constructor, to create an object of this class without creating an additional thread of execution. You can subsequently start execution of the thread using IThread::start.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
protected:
IThread& operator =(const IThread& thread)
Assigns the member data of an object of this class to another object of this class, therefore preserving resource allocation.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Graphical User Interface (GUI) SupportUse these members to query and set the thread specific information used by the GUI.
![]() |
public:
virtual IWindowHandle applicationShell() const
Obtains the application shell handle for the current thread. If the application shell handle is not initialized, 0 is returned. Use ICurrentThread::initializeGUI to initialize the application shell.
For portable applications, use IWindow::desktopWindow to obtain the handle of the window to use as the parent of your application's top level windows.
| Windows | OS/2 | AIX |
| No | No | Yes |
![]() |
public:
virtual bool autoInitGUI() const
Determines if this thread's GUI support is automatically initialized.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static bool defaultAutoInitGUI()
Determines the default GUI support for automatic initialization. Unless the support is explicitly set using IThread::setDefaultAutoInitGUI, this function returns true for threads running in a GUI session and false for threads running in a non-GUI session.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Unless the support is explicitly set using IThread::setDefaultAutoInitGUI, this function always returns true.
![]() |
public:
bool isProcessingMsgs() const
Returns true if the thread has an active user interface event processing loop. This is true when the ICurrentThread::processMsgs function is active in the thread.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
virtual IThread& setAutoInitGUI(bool initFlag = true)
Sets the automatic initialization state for this thread. Set initFlag to true, the default, for GUI-based threads and to false for non-GUI-based threads.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void setDefaultAutoInitGUI(bool initFlag = true)
Sets the default GUI support for automatic initialization. Set initFlag to true, the default, if you want the GUI to automatically be initialized.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
virtual IThread& stopProcessingMsgs()
Terminates the processing of window events (messages) initiated by ICurrentThread::processMsgs.
| IInvalidRequest | The event processing was not terminated. The termination failed because the event processing was not initiated by ICurrentThread::processMsgs. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
ImplementationThese members provide utilities used to implement this class. They are used by the Open Class Library and are not intended for use by users of this class.
![]() |
protected:
static IStartedThread* newStartedThread()
Creates an object of the IStartedThread class.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
protected:
virtual IStartedThread* startedThread() const
Returns a pointer to the object of the IStartedThread class that corresponds to this thread.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Message QueueUse these members to query and set message queue information for graphical user interface (GUI) support.
![]() |
public:
static long defaultQueueSize()
Obtains the default message queue size for the threads.
The Open Class Library default queue size is 30.
Note:
| Windows | OS/2 | AIX |
| Ignored | Yes | Ignored |
This function returns the queue size that is set by IThread::setDefaultQueueSize.
This member obtains the default Presentation Manager message queue size to use for new IThreads.
This function returns the queue size that is set by IThread::setDefaultQueueSize.
![]() |
Returns the handle of the message queue. A 0 is returned if the handle does not exist or is invalid.
public:
IMessageQueueHandle messageQueue() const
Use this version of the function if you want the invalid message queue handle to remain invalid.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
The message queue handle and thread identifier are identical.
The message queue handle and thread identifier are identical.
public:
IMessageQueueHandle messageQueue()
Use this version of the function if you want to reset an invalid message queue handle to 0. Do this if the handle is determined to be invalid.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
The message queue handle and thread identifier are identical.
The message queue handle and thread identifier are identical.
![]() |
Places an event constructed from the parameters on a thread's user interface event queue. This function does not wait for the target thread to process the event. The event is directed to the thread's event processing loop itself rather than a specific window. Use IWindow::postEvent or IWindowHandle::postEvent to direct an event to a specific window.
public:
void postEvent( unsigned long eventId, const IEventParameter1& parm1 = 0ul, const IEventParameter2& parm2 = 0ul ) const
Places the event on this thread's event queue.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
static void postEvent( const IThread& thread, unsigned long eventId, const IEventParameter1& parm1 = 0ul, const IEventParameter2& parm2 = 0ul )
Places the event on the specified thread's event queue.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void postEvents( unsigned long eventId, const IEventParameter1& parm1 = 0ul, const IEventParameter2& parm2 = 0ul )
Broadcasts an event to other threads' user interface event queues asynchronously.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
This function places the event on the current thread's event queue. It does not post the event to all applications in the system.
![]() |
public:
virtual long queueSize() const
Obtains the message queue size for the thread. This is the queue used by the application to receive events from the operating system.
| Windows | OS/2 | AIX |
| Ignored | Yes | Ignored |
This function returns the queue size that is set by IThread::setQueueSize.
This function returns the queue size that is set by IThread::setQueueSize.
![]() |
public:
static void setDefaultQueueSize(long queueSize)
Sets the default message queue size for threads. The Open Class Library default queue size is 30.
Note:
| Windows | OS/2 | AIX |
| Ignored | Yes | Ignored |
This function has no effect on the message queue size. The value set by this function is the value returned by IThread::defaultQueueSize.
This function has no effect on the message queue size. The value set by this function is the value returned by IThread::defaultQueueSize.
![]() |
public:
virtual IThread& setQueueSize(long queueSize)
Sets the GUI message queue size for this thread.
| Windows | OS/2 | AIX |
| Ignored | Yes | Ignored |
This function has no effect on the size of the message queue. The value set by this function is the value returned by IThread::queueSize.
This function has no effect on the size of the message queue. The value set by this function is the value returned by IThread::queueSize.
Starting and Stopping ThreadsUse these members to start or stop threads.
![]() |
Starts an asynchronous thread.
public:
virtual void start( SystemFnPtr function, unsigned long functionArgument, bool autoInitGUI )
You can start threads with a function that is defined using the _System calling convention. Such functions are typically started using the thread APIs that are defined for the operating system. This function gives you the same capability.
This function permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
virtual void start( OptlinkFnPtr function, void* functionArgument, bool autoInitGUI )
You can start threads with a function that is defined using the _Optlink calling convention. Such functions are typically started using the function, _beginThread. This function gives you the same capability.
This function permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
virtual void start( OptlinkFnPtr function, void* functionArgument )
This function is identical to the INonGUIThread::start function with the same arguments. It does not perform GUI initialization.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
virtual void start(IThreadFn* threadFunction)
This function is identical to the INonGUIThread::start function with the same arguments. It does not perform GUI initialization.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
virtual void start( IThreadFn* threadFunction, bool autoInitGUI )
Use this function to start a thread when you need to specify a function to run in the new thread. You define this function by deriving a new class from the IThreadFn class. This function takes ownership of the derived IThreadFn object you provide so that Open Class Library can delete this object when the thread terminates.
This function permits you to specify whether the new thread is to initialize the GUI. If it is, ICurrentThread::initializeGUI is called automatically after the thread is started. Specify false for this argument if you need to perform specialized processing prior to initializing the GUI.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
virtual void start( SystemFnPtr function, unsigned long functionArgument )
This function is identical to the INonGUIThread::start function with the same arguments. It does not perform GUI initialization.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
virtual void stop()
Stops the thread. This function causes the thread to stop immediately, bypassing some normal termination functions. Use it with extreme caution, preferably when the state of the target thread is known.
| IAccessError | The thread was not stopped. The thread was either busy or the thread identifier (ID) is invalid. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Do not use this function on suspended threads or the results can be unpredictable.
Thread InformationUse these members to query and set general thread information.
![]() |
public:
static ICurrentThread& current()
Returns a reference to an object of the ICurrentThread class that represents the currently executing thread.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
virtual ~INonGUIThread()
virtual INonGUIThread& adjustPriority(int delta)
virtual IString asDebugInfo() const
virtual IString asString() const
static int
convertedPriority( const int toConvert,
INonGUIApplication::PriorityClass& classToSet )
static ICurrentNonGUIThread& current()
static IThreadHandle currentHandle()
static IThreadId currentId()
static unsigned long defaultStackSize()
unsigned long exitCode() const
virtual IThreadHandle handle() const
virtual IThreadId id() const
INonGUIThread( OptlinkFnPtr function,
void* functionArgument )
INonGUIThread( SystemFnPtr function,
unsigned long functionArgument )
INonGUIThread(const INonGUIThread& thread)
INonGUIThread()
INonGUIThread( const IThreadId& threadID, const IThreadHandle& threadHandle = IThreadHandle::noHandle )
INonGUIThread(IThreadFn*)
virtual bool isStarted() const
virtual INonGUIApplication::PriorityClass priorityClass() const
virtual unsigned priorityLevel() const
virtual void resume()
static void setDefaultStackSize(unsigned long size)
virtual INonGUIThread& setPriority( INonGUIApplication::PriorityClass priority, unsigned level )
virtual INonGUIThread& setStackSize(unsigned long size)
virtual INonGUIThread& setThreadPriority( const INonGUIThread::EThreadPriority newPriority )
INonGUIThread& setVariable( const IString& key, const IString& value )
virtual unsigned long stackSize() const
virtual void start(IThreadFn*)
virtual void suspend()
virtual INonGUIThread::EThreadPriority threadPriority() const
IString variable(const IString& key) const
INonGUIThread& operator =(const INonGUIThread& thread)