ICurrentThread

The ICurrentThread class represents the current thread of execution. An object of this class contains information that the Open Class Library maintains for the current thread of execution. You are limited to a single object of this class.

This class provides functions that you can only apply to the current thread of execution. To obtain a reference to the object, use the static function IThread::current.

This class provides functions related to graphical user interface support such as initialization, termination and event processing. If the current thread does not have GUI windows, use ICurrentNonGUIThread instead of this class.


ICurrentThread - Member Functions and Data by Group

Constructors & Destructor

Use these protected constructors to construct objects of this class.


[view class]
ICurrentThread
protected:
ICurrentThread()

The constructor is protected to prevent the accidental creation of objects of this class. Creation of objects of this class is restricted to IThread::current.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Current Thread Support

Use these members to perform thread operations that only apply to the current thread.


[view class]
exit
public:
virtual void exit(unsigned long returnCode)

Ends the current thread with the specified return value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Determines if the application shell window is completely initialized. If it is, true is returned.

Supported Platforms

Windows OS/2 AIX
No No Yes


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

Determines if an X Library error code is available for querying. If one is available, true is returned. This function uses XerrorCode to retrieve the error code, which resets this flag.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
remainingStack
public:
virtual unsigned long remainingStack() const

Obtains an approximation of the number of available bytes that remain on the stack. If the stack is not initialized, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

This function always returns 1000 because an approximation cannot be obtained.


[view class]
sleep
public:
virtual ICurrentThread& sleep(unsigned long milliseconds)

Suspends the thread for a specified number of milliseconds.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The granularity for sleeping on AIX is in seconds. The number of milliseconds is divided by 1000 to determine the number of seconds the thread will sleep. If the number of milliseconds is less than 1 second, the thread will not sleep.


[view class]
waitFor
public:
virtual ICurrentThread& waitFor( const INonGUIThread& anotherThread, long timeout = - 1 )

Allows the current thread to wait for a specified thread to end.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
waitForAllThreads
public:
virtual ICurrentThread& waitForAllThreads( long timeout = - 1, bool* timedOut = 0 )
Allows the main thread to wait for all other threads that were started using INonGUIThread or IThread to end. This function may only be called from the main thread of the process.

timeout
-1 means wait indefinitely, 0 means do not wait, other positive values give the timeout period in milliseconds.
timedOut
An optional boolean value that is set to indicate whether the return was because of a timeout or a successful wait.

Exception

IInvalidParameter is thrown if this function is called from a thread other than the main thread of the process.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
waitForAnyThread
public:
virtual IThreadId waitForAnyThread(long timeout = - 1)

Allows the current thread to wait for the first termination to occur of any other threads in the current process. The terminated thread's identifier (ID) is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Graphical User Interface (GUI) Support

Use these members to support GUI activities on the current thread.


[view class]
anchorBlock
public:
virtual IAnchorBlockHandle anchorBlock() const

Obtains the anchor block handle for the current thread. If the anchor block handle is not initialized, 0 is returned. Use ICurrentThread::initializeGUI to initialize the anchor block handle.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

AIX Considerations

The value returned by this function is the application context (XtAppContext) returned by XtAppInitialize.

OS/2 Considerations

The value returned by this function is the anchor block handle (HAB) returned by WinInitialize.

Windows Considerations

This function always returns 1 because Windows has no concept of an anchor block.


[view class]
initializeGUI
public:
virtual void initializeGUI(long queueSize = 30)

Allocates the system resources necessary for the current thread to process graphical user interface (GUI) events. Use ICurrentThread::terminateGUI to deallocate these resources.

Exception

IAccessError The graphical user interface (GUI) was not initialized. The window initialization failed.
IAccessError The graphical user interface (GUI) was not initialized. The message queue creation failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Insures that the X environment is initialized. If needed, this function calls XtSetLanguageProc to establish the default locale and XtAppInitialize to create the application context and application shell. The queueSize parameter has no effect.

OS/2 Considerations

Insures that the Presentation Manager environment is initialized. If needed, this function initializes the environment by calling WinInitialize and WinCreateMessageQueue.

Windows Considerations

The queueSize parameter has no effect because you cannot specify a queue size under Windows.


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

Determines if the graphical user interface (GUI) environment is active for this thread. If the GUI is active, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
messageQueue

Obtains the message queue handle for the current thread. A 0 is returned if the handle is not initialized or is invalid.


Overload 1
public:
virtual 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

Windows Considerations

Returns the current thread's identifier.


Overload 2
public:
virtual 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

Windows Considerations

Returns the current thread's identifier.


[view class]
processMsgs
public:
virtual void processMsgs()

Activates a user interface event processing loop. This function retrieves events from the system message queue and dispatches them until event processing is stopped by the system or by IThread::stopProcessingMessages.

Use IThread::isProcessingMsgs to determine if this function is running on a thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

ICurrentThread dispatches messages until it receives the client message WM_QUIT or the application is terminated through the Motif Window Manager.

OS/2 Considerations

Messages are dispatched until the WM_QUIT message is received.


[view class]
terminateGUI
public:
virtual void terminateGUI()

Terminates the graphical user interface (GUI) environment. If you start a thread using the IThread constructors or IThread::start and specify true for the autoInitGUI argument, this function is called automatically by the Open Class Library when your thread function or the IThreadFn::run function returns. For the IThread constructors, the value of autoInitGUI is provided by the IThread::autoInitGUI function when you omit the autoInitGUI argument.

If you do the following, the Open Class Library does not call this function automatically, and it is your responsibility to do so:


Note: If you do not call this function and it is your responsibility to do so, you can tie up system resources until your application ends.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

OS/2 Considerations

Before calling the WinTerminate API, the application must destroy (that is delete) all windows and the message queue. This function destroys the message queue, but it is still the application's responsibility to destroy all of the window objects for the thread. If it does not, the return value of WinTerminate and any subsequent calls is indeterminate.

Windows Considerations

This function has no effect because the message queue is automatically destroyed by Windows.


Implementation

These members provide utilities used to implement this class. They are used by the Open Class Library.


[view class]
setTopLevelShell
public:
virtual void setTopLevelShell() const

Called when the application shell window has been initialized. The Open Class Library calls this function to prevent multiple initializations of the graphical user interface.
Note: A user of the Open Class Library should never call this member function.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
setXerrorCode
public:
virtual void setXerrorCode(int errorCode)

Sets the error code that the last call to an X Library function reported. Typically, you use this function to save the error code detected by the handler set by XSetErrorHandler in IThread. The error handler is set by IThread so that the error codes are maintained on a per thread basis.
Note: A user of the Open Class Library should never call this member function.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
XerrorCode
public:
virtual int XerrorCode() const

Returns the X Library error code set by the member function ICurrentThread::setXerrorCode. You can retrieve the error code until a new X Library error code is set by ICurrentThread::setXerrorCode, but the flag indicating that an error code is available is reset on the first invocation. The class IXLibErrorInfo uses this function to obtain information about the last X Library error code detected.
Note: A user of the Open Class Library should never call this member function.

Supported Platforms

Windows OS/2 AIX
No No Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Suspending Threads

Use these members to suspend your current thread of execution if the thread is a non-GUI thread. Use IThread::resume to resume execution of the thread.


[view class]
suspend
public:
virtual void suspend()

Suspends the current thread of execution only if the graphical user interface (GUI) is not initialized for the thread. Suspending a GUI-initialized thread can cause your application to hang.

Exception

IInvalidRequest The current thread was not suspended. A GUI thread cannot be suspended, or the application may hang.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICurrentThread - Inherited Member Functions and Data

Inherited Public Functions

INonGUIThread
IThread
ICurrentThread

Inherited Public Data

Inherited Protected Functions

IThread
INonGUIThread

Inherited Protected Data