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

~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

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

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.

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

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

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.

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

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

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

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.

newStartedThread

      protected:
      static IStartedThread* newStartedThread()

  Creates an object of the IStartedThread class.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

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.

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

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.

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.

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.

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.

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

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.

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

  -     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

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  INonGUIThread

  -     INonGUIThread& operator =(const INonGUIThread& thread)

#### Inherited Protected Data

  - None