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

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.

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

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

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

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.

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.

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

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

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.

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.

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.

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

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.

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.

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:

  - Start the thread using any other means including the INonGUIThread constructors or start functions, operating system functions, or the _beginthread function
  - Specify false for autoInitGUI on the IThread contructors or start functions.
  - Omit autoInitGUI on the IThread::start functions.
  - Stop the thread before it returns, such as by using IThread::stop, INonGUIThread::stop, ICurrentThread::exit or INonGUIThread::exit
  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.

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

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

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

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.

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

  -     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( const IThreadId& threadID,
                       const IThreadHandle& threadHandle = IThreadHandle::noHandle )

  -     INonGUIThread()

  -     INonGUIThread( SystemFnPtr function,
                       unsigned long functionArgument )

  -     INonGUIThread(IThreadFn*)

  -     INonGUIThread(const INonGUIThread& thread)

  -     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 INonGUIThread::EThreadPriority
          threadPriority() const

  -     IString variable(const IString& key) const

  IThread

  -     virtual ~IThread()

  -     virtual IWindowHandle applicationShell() const

  -     virtual bool autoInitGUI() const

  -     static ICurrentThread& current()

  -     static bool defaultAutoInitGUI()

  -     static long defaultQueueSize()

  -     bool isProcessingMsgs() const

  -     IThread()

  -     IThread( IThreadFn* threadFunction,
                 bool autoInitGUI = defaultAutoInitGUI ( ) )

  -     IThread(const IThread& thread)

  -     IThread( OptlinkFnPtr function,
                 void* functionArgument,
                 bool autoInitGUI = defaultAutoInitGUI ( ) )

  -     IThread( const IThreadId& threadID,
                 const IThreadHandle& threadHandle = IThreadHandle ( ) )

  -     IThread( SystemFnPtr function,
                 unsigned long functionArgument,
                 bool autoInitGUI = defaultAutoInitGUI ( ) )

  -     IMessageQueueHandle messageQueue() const

  -     IMessageQueueHandle messageQueue()

  -     static void
          postEvent( const IThread& thread,
                     unsigned long eventId,
                     const IEventParameter1& parm1 = 0ul,
                     const IEventParameter2& parm2 = 0ul )

  -     void
          postEvent( unsigned long eventId,
                     const IEventParameter1& parm1 = 0ul,
                     const IEventParameter2& parm2 = 0ul ) const

  -     static void
          postEvents( unsigned long eventId,
                      const IEventParameter1& parm1 = 0ul,
                      const IEventParameter2& parm2 = 0ul )

  -     virtual long queueSize() const

  -     virtual IThread& setAutoInitGUI(bool initFlag = true)

  -     static void setDefaultAutoInitGUI(bool initFlag = true)

  -     static void setDefaultQueueSize(long queueSize)

  -     virtual IThread& setQueueSize(long queueSize)

  -     virtual void
          start( SystemFnPtr function,
                 unsigned long functionArgument,
                 bool autoInitGUI )

  -     virtual void
          start( OptlinkFnPtr function,
                 void* functionArgument,
                 bool autoInitGUI )

  -     virtual void start(IThreadFn* threadFunction)

  -     virtual void
          start( IThreadFn* threadFunction,
                 bool autoInitGUI )

  -     virtual void
          start( SystemFnPtr function,
                 unsigned long functionArgument )

  -     virtual void
          start( OptlinkFnPtr function,
                 void* functionArgument )

  -     virtual void stop()

  -     virtual IThread& stopProcessingMsgs()

  ICurrentThread

  -     virtual IMessageQueueHandle messageQueue() const

  -     void
          setAnchorBlock( const IWindowHandle& appShell,
                          const IAnchorBlockHandle& appContext )

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IThread

  -     static IStartedThread* newStartedThread()

  -     IThread& operator =(const IThread& thread)

  INonGUIThread

  -     INonGUIThread& operator =(const INonGUIThread& thread)

#### Inherited Protected Data

  - None