IThread

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.

AIX Considerations

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.


IThread - Member Functions and Data by Group

Constructors & Destructor

You can construct, copy, assign, and destruct objects of this class.


[view class]
~IThread
public:
virtual ~IThread()

Deallocates thread-related resources.
Note: When objects of this class are destructed, the thread is not terminated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IThread


Overload 1
public:
IThread( SystemFnPtr function, unsigned long functionArgument, bool autoInitGUI = defaultAutoInitGUI ( ) )

function
Pointer to a function that uses the _System calling convention.
functionArgument
Unsigned long parameter that you are passing to the function pointed to by function.
autoInitGUI
A boolean value that you use to specify that the GUI is to be initialized for the new thread.

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.

Exception

IInvalidRequest The thread cannot be started; Win32s does not support multiple threads.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IThread(const IThread& thread)

thread
Reference to an object of this class.

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IThread( IThreadFn* threadFunction, bool autoInitGUI = defaultAutoInitGUI ( ) )

threadFunction
Pointer to an object created using a class derived from IThreadFn.
autoInitGUI
A boolean value that you use to specify that the GUI is to be initialized for the new thread.

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.

Exception

IInvalidRequest The thread cannot be started; Win32s does not support multiple threads.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IThread( OptlinkFnPtr function, void* functionArgument, bool autoInitGUI = defaultAutoInitGUI ( ) )

function
Pointer to a function that uses the _Optlink calling convention.
functionArgument
Pointer to a parameter that you are passing to the function pointed to by function.
autoInitGUI
A boolean value that you use to specify that the GUI is to be initialized for the new thread.

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.

Exception

IInvalidRequest The thread cannot be started; Win32s does not support multiple threads.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IThread( const IThreadId& threadID, const IThreadHandle& threadHandle = IThreadHandle ( ) )

threadID
Reference to a thread identifier of a previously started thread.
threadHandle
Optional reference to a thread handle of a previously started thread.

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).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The threadHandle parameter is ignored.

OS/2 Considerations

The threadHandle parameter is ignored.

Windows Considerations

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.


Overload 6
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Graphical User Interface (GUI) Support

Use these members to query and set the thread specific information used by the GUI.


[view class]
applicationShell
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.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
autoInitGUI
public:
virtual bool autoInitGUI() const

Determines if this thread's GUI support is automatically initialized.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultAutoInitGUI
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Unless the support is explicitly set using IThread::setDefaultAutoInitGUI, this function always returns true.


[view class]
isProcessingMsgs
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAutoInitGUI
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultAutoInitGUI
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stopProcessingMsgs
public:
virtual IThread& stopProcessingMsgs()

Terminates the processing of window events (messages) initiated by ICurrentThread::processMsgs.

Exception

IInvalidRequest The event processing was not terminated. The termination failed because the event processing was not initiated by ICurrentThread::processMsgs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These 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.


[view class]
newStartedThread
protected:
static IStartedThread* newStartedThread()

Creates an object of the IStartedThread class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
startedThread
protected:
virtual IStartedThread* startedThread() const

Returns a pointer to the object of the IStartedThread class that corresponds to this thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Message Queue

Use these members to query and set message queue information for graphical user interface (GUI) support.


[view class]
defaultQueueSize
public:
static long defaultQueueSize()

Obtains the default message queue size for the threads. The Open Class Library default queue size is 30.
Note: The Open Class Library uses this value by default for new objects of this class.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This function returns the queue size that is set by IThread::setDefaultQueueSize.

OS/2 Considerations

This member obtains the default Presentation Manager message queue size to use for new IThreads.

Windows Considerations

This function returns the queue size that is set by IThread::setDefaultQueueSize.


[view class]
messageQueue

Returns the handle of the message queue. A 0 is returned if the handle does not exist or is invalid.


Overload 1
public:
IMessageQueueHandle messageQueue() const

Use this version of the function if you want the invalid message queue handle to remain invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The message queue handle and thread identifier are identical.

Windows Considerations

The message queue handle and thread identifier are identical.


Overload 2
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The message queue handle and thread identifier are identical.

Windows Considerations

The message queue handle and thread identifier are identical.


[view class]
postEvent

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.


Overload 1
public:
void postEvent( unsigned long eventId, const IEventParameter1& parm1 = 0ul, const IEventParameter2& parm2 = 0ul ) const

Places the event on this thread's event queue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
postEvents
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function places the event on the current thread's event queue. It does not post the event to all applications in the system.


[view class]
queueSize
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.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This function returns the queue size that is set by IThread::setQueueSize.

Windows Considerations

This function returns the queue size that is set by IThread::setQueueSize.


[view class]
setDefaultQueueSize
public:
static void setDefaultQueueSize(long queueSize)

Sets the default message queue size for threads. The Open Class Library default queue size is 30.
Note: The Open Class Library uses this value by default for new objects of this class.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This function has no effect on the message queue size. The value set by this function is the value returned by IThread::defaultQueueSize.

Windows Considerations

This function has no effect on the message queue size. The value set by this function is the value returned by IThread::defaultQueueSize.


[view class]
setQueueSize
public:
virtual IThread& setQueueSize(long queueSize)

Sets the GUI message queue size for this thread.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

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.

Windows Considerations

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 Threads

Use these members to start or stop threads.


[view class]
start

Starts an asynchronous thread.


Overload 1
public:
virtual void start( SystemFnPtr function, unsigned long functionArgument, bool autoInitGUI )

function
Pointer to a function that uses the _System calling convention.
functionArgument
Unsigned long parameter that you are passing to the function pointed to by pfn.
autoInitGUI
A boolean value that you use to specify if the thread is a GUI thread.

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual void start( OptlinkFnPtr function, void* functionArgument, bool autoInitGUI )

function
Pointer to a function that uses the _Optlink calling convention.
functionArgument
Pointer to a parameter that you are passing to the function pointed to by pfn.
autoInitGUI
A boolean value that you use to specify that the GUI is to be initialized for the new thread.

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
virtual void start( IThreadFn* threadFunction, bool autoInitGUI )

threadFunction
Pointer to an object created using a class derived from IThreadFn.
autoInitGUI
A boolean value that you use to specify that the GUI is to be initialized for the new thread.

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stop
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.

Exception

IAccessError The thread was not stopped. The thread was either busy or the thread identifier (ID) is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

Do not use this function on suspended threads or the results can be unpredictable.


Thread Information

Use these members to query and set general thread information.


[view class]
current
public:
static ICurrentThread& current()

Returns a reference to an object of the ICurrentThread class that represents the currently executing thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IThread - Inherited Member Functions and Data

Inherited Public Functions

INonGUIThread

Inherited Public Data

Inherited Protected Functions

INonGUIThread

Inherited Protected Data