### INonGUIThread

  The INonGUIThread class represents threads of execution within the current program. You can use this class to implement multithreaded applications. Objects of this class give you access to all of the tasking APIs of the operating system. In addition, these objects can serve as the anchor for thread-specific information.

  Generally, you use objects of this class in one of the following ways:

  - To apply thread functions to the current thread. In most cases, these functions are applied to the INonGUIThread object reference returned by the static member function INonGUIThread::current.
  - To create additional threads of execution by creating new objects of this class and starting them.
  - To manipulate threads of execution initiated using alternate means, for which only the thread's identifier is known.

  If you intend to create or manipulate graphical user interface (GUI) objects in a thread, use the derived class IThread instead of this class. It provides members to manage thread specific information needed by the operating system's GUI components.

### INonGUIThread - Member Functions and Data by Group

### Constructors & Destructor

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

~INonGUIThread

      public:
      virtual ~INonGUIThread()

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

Supported Platforms

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

INonGUIThread
  Constructs a non-GUI thread object. In the case of the default constructor, the start() must be called to actually start the thread. The other constructors accept the thread function and optional parameters and start the thread immediately.

  Overload 1

      public:
      INonGUIThread()

  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 INonGUIThread::start.

Supported Platforms

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

  Overload 2

      public:
      INonGUIThread(const INonGUIThread& 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.

  Note that copying an INonGUIThread object does not start new thread of execution. The newly copied INonGUIThread will refer to the same actual thread of execution as the original (source in the copy) INonGUIThread.

  thread
    The source thread to copy construct from

Supported Platforms

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

  Overload 3

      public:
      INonGUIThread( OptlinkFnPtr function,
                     void* functionArgument )

  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 INonGUIThread::start.

  function
    The _Optlink style function to use as the function pointer for this thread

    functionArgument The optional thread parameters to pass to the thread

Supported Platforms

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

  Overload 4

      public:
      INonGUIThread(IThreadFn*)

  Create a INonGUIThread object and start a new thread running. The code to be run in the new thread is specified by the run() method of the IThreadFn object passed in as a parameter.

  Ownership of the storage for the IThreadFn object is taken on by the INonGUIThread object, which will delete it when the new thread completes execution.

  IThreadFn
    specifies the code to be executed in the new thread.

Supported Platforms

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

  Overload 5

      public:
      INonGUIThread( const IThreadId& threadID,
                     const IThreadHandle& threadHandle = IThreadHandle::noHandle )

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

  threadID
    The thread id of the thread to wrap

    threadHandle The handle of the thread to wrap

Supported Platforms

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

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:
      INonGUIThread( SystemFnPtr function,
                     unsigned long functionArgument )

  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 INonGUIThread::start.

  function
    The _System linkage style function to use as the thread function for this thread object.

    functionArgument The optional thread parameters to pass to the thread function.

Supported Platforms

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

### Deprecated Priority Methods

These methods are deprecated, and represent the old OS/2 centric thread priority scheme. These have been replaced by newer, more portable priority methods.

adjustPriority

      public:
      virtual INonGUIThread& adjustPriority(int delta)

  Changes the thread's priority level by the specified amount. This is a deprecated API that is only supported on OS/2, for backwards compability.

  delta
    The amount to adjust the thread priority level by

Return
  A reference to this object.

Exception

  IAccessError | The thread priority was not adjusted. The priority delta may be invalid. The valid values are -31 to 31.

Supported Platforms

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

OS/2 Considerations

  The delta value is between -31 and 31.

convertedPriority

      public:
      static int
        convertedPriority( const int toConvert,
                           INonGUIApplication::PriorityClass& classToSet )

  Converts a stored priority level into the old style OS/2 specific priority class and level. This is only for use on OS/2, to maintain backwards compability.

  toConvert
    The stored priority to convert
  classToSet
    The OS/2 priority class to which the passed priority maps

Return
  The priority level that was mapped to.

Supported Platforms

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

priorityClass

      public:
      virtual INonGUIApplication::PriorityClass
        priorityClass() const

  Obtains the priority class of this thread. The return value is an enumerator provided by INonGUIApplication::PriorityClass. This is a deprecated method and supported only on OS/2, for backwards compability purposes.

Return
  The non-portable (OS/2 specific) thread priority class of the thread.

Supported Platforms

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

AIX Considerations

  The priority class for AIX is always INonGUIApplication::regular.

OS/2 Considerations
  Note that this API is deprecated and only available on OS/2 at this time. There are new, portable priority APIs that are not OS/2 specific.

priorityLevel

      public:
      virtual unsigned priorityLevel() const

  Obtains the priority level of this thread. The return value is between 0 and 31. This is a deprecated method, and is only supported on OS/2, for backwards compability reasons.

Return
  The non-portable (OS/2 specific) priority level of this thread.

Supported Platforms

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

OS/2 Considerations
  Note that this API is deprecated and only available on OS/2 at this time. There are new, portable priority APIs that are not OS/2 specific.

setPriority

      public:
      virtual INonGUIThread&
        setPriority( INonGUIApplication::PriorityClass priority,
                     unsigned level )

  Sets the priority class and level of this thread. This is a deprecated API suppored only on OS/2, for backwards compatibility.

  priority
    The new priority class to set
  level
    The new priority level to set

Return
  A reference to this object.

Exception

  IAccessError | The thread priority was not set. The priority class or level may be invalid.

Supported Platforms

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

AIX Considerations

  You cannot control the priority of a thread in the AIX environment. This function has no effect on the priority of an executing thread.

### Diagnostics

Use these members for diagnostic purposes. They return an IString representation of an object of this class.

asDebugInfo

      public:
      virtual IString asDebugInfo() const

  Provides debugging information about the class object. Use it to return general diagnostic information about the thread.

Return
  An IString object with this object's debug information in it.

Supported Platforms

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

asString

      public:
      virtual IString asString() const

  Provides debugging information about the class object. Use it to return a string of the form "INonGUIThread(tid)", where tid represents the thread identifier.

Return
  An IString object with this object's debug information in it.

Supported Platforms

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

### Stack Size

Use these members to query and set this thread's stack size.

defaultStackSize

      public:
      static unsigned long defaultStackSize()

  Obtains the default stack size for threads in bytes. The Open Class Library uses this value by default for new objects of this class.

Return
  The default stack size current set on this object.

Supported Platforms

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

setDefaultStackSize

      public:
      static void setDefaultStackSize(unsigned long size)

  Sets the default stack size for threads in bytes. The Open Class Library uses this value by default for new objects of this class.

  size
    The new default stack size to set for this thread.

Supported Platforms

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

setStackSize

      public:
      virtual INonGUIThread& setStackSize(unsigned long size)

  Sets this thread's stack size in bytes. If you have already started the thread, this value takes effect only when the thread is stopped and restarted.

  size
    The new stack size to set for this thread.

Return
  A reference to this object.

Supported Platforms

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

OS/2 Considerations

  This value controls the maximum amount of storage which can be used by the thread's stack. When the thread is started, the system allocates a small initial stack. When additional stack space is needed the system automatically allocates additional stack space up to the amount specified using this function.

Windows Considerations

  This value controls the amount of storage which will be committed to the thread by the system when the thread is started. Additional storage, up to the maximum available to your program, will be automatically allocated by the system if needed. You can control the maximum available stack available to your program by using the /STACKSIZE linker directive.

stackSize

      public:
      virtual unsigned long stackSize() const

  Obtains this thread's stack size in bytes. If it was set when the thread was running, it might not reflect the size of the currently running thread. It only takes affect the next time the thread is started.

Return
  The stack size of this thread object

Supported Platforms

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

Windows Considerations

  Returns the value of the stack size that was set with the function INonGUIThread::setStackSize. This value represents the stack size used as the initial stack size when the thread is created. For the primary thread, its value is the same as the initial default stack size. This value does not represent the actual committed stack in use by the thread.

  You can control the maximum available stack available to your program by using the /STACKSIZE linker directive.

### Starting and Stopping Threads

Use these members to start or stop threads.

resume

      public:
      virtual void resume()

  Resumes a thread's execution after it has been suspended by a call to suspend(). Note that suspend() and resume() are not recommended mechanisms for thread control. Resources and conditions provide safer services for managing threads.

Exception

  IAccessError | The thread was not suspended or the thread is invalid.

Supported Platforms

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

start
  Starts a thread, providing the function that will be the thread's starting point in a number of different ways, and optionally providing thread arguments that will be passed along to the new thread. Ownership of the storage for the IThreadFn object is taken on by the INonGUIThread object, which will delete it when the new thread completes execution.

  Overload 1

      public:
      virtual void
        start( SystemFnPtr function,
               unsigned long functionArgument )

  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.

  functionArgument
    The _System style function to start the thread on.

Exception

  IInvalidRequest | If the thread has already been started.

Supported Platforms

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

  Overload 2

      public:
      virtual void start(IThreadFn*)

Exception

  IInvalidRequest | If the thread has already been started.

Supported Platforms

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

  Overload 3

      public:
      virtual void
        start( OptlinkFnPtr function,
               void* functionArgument )

  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.

  functionArgument
    The _Optlink style function to start the thread on.

Exception

  IInvalidRequest | If the thread has already been started.

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

suspend

      public:
      virtual void suspend()

  Suspends the thread's execution, which can be undone later with a call to resume(). Note that suspend() and resume() are not recommended mechanisms for thread control. Resources and conditions provide safer services for managing threads.

Exception

  IAccessError | (OS/2 and Windows) The thread is invalid. The thread was not suspended. (DD) IInvalidRequest (AIX) The suspend function is not supported.

Supported Platforms

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

AIX Considerations

  This function is not supported. If you call it Open Class Library throws an exception.

### Thread Information

Use these members to query and set general thread information.

current

      public:
      static ICurrentNonGUIThread& current()

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

Return
  A reference to the thread object for the calling thread.

Supported Platforms

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

currentHandle

      public:
      static IThreadHandle currentHandle()

  Returns the thread handle for the current thread.

Return
  The thread handle of the calling thread.

Supported Platforms

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

AIX Considerations

  The thread handle and thread ID are identical.

OS/2 Considerations

  The thread handle and thread ID are identical.

Windows Considerations

  You must use the thread handle for the operating system thread and synchronization functions.

currentId

      public:
      static IThreadId currentId()

  Obtains the identifier of the currently executing thread.

Return
  The thread id of the calling thread.

Supported Platforms

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

exitCode

      public:
      unsigned long exitCode() const

  Returns the exit code for the thread. If the thread is still running, then the value is undefined.

Return
  The exit code left by this thread when it terminated.

Supported Platforms

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

handle

      public:
      virtual IThreadHandle handle() const

  Returns the thread handle for this object's thread.

Return
  This thread's handle

Supported Platforms

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

AIX Considerations

  The thread handle and thread ID are identical.

OS/2 Considerations

  The thread handle and thread ID are identical.

Windows Considerations

  You must use the thread handle for the operating system thread and synchronization functions.

id

      public:
      virtual IThreadId id() const

  Obtains the identifier of the thread. A return value of 0 indicates that the thread is not started.

Return
  This thread's id

Supported Platforms

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

isStarted

      public:
      virtual bool isStarted() const

  Determines if this thread is currently active. If it is currently active, true is returned.

Return
  true if the thread is running, else false.

Supported Platforms

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

setVariable

      public:
      INonGUIThread&
        setVariable( const IString& key,
                     const IString& value )

  Stores data and an associated key, on a per thread instance. You can later retrieve this data using INonGUIThread::variable.

  key
    The name of the new thread variable to set

    value The new value to give to the new thread variable.

Return
  A reference to this object.

Supported Platforms

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

variable

      public:
      IString variable(const IString& key) const

  Returns the data associated with the key that was stored using INonGUIThread::setVariable. If there is no data associated with the key, IString() is returned.

  key
    The name of the thread variable to query

Return
  An IString object with the value of the passed variable.

Supported Platforms

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

### Thread Priority

Use these members to control the thread's priority. You can query or set the priority class and level.

setThreadPriority

      public:
      virtual INonGUIThread&
        setThreadPriority( const INonGUIThread::EThreadPriority newPriority )

  This is the new, portable, mechanism for setting thread priorities. Threads only have a priority level, but no priorrity class (as was the case in the original OS/2 specific implementation.)

  newPriority
    The new portable thread priority level to set for this thread.

Return
  A reference to this object.

Exception

  IAccessError | Failed to set the thread priority.

Supported Platforms

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

threadPriority

      public:
      virtual INonGUIThread::EThreadPriority
        threadPriority() const

  This is the new, portable, mechanism for retrieving a thread's priority. Threads only have a priority level, but no priorrity class (as was the case in the original OS/2 specific implementation.)

Return
  The portable thread priority level of this thread.

Supported Platforms

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

### INonGUIThread - Enumerations

EThreadPriority

      enum EThreadPriority { idle=1000,
                             belowNormal=1001,
                             normal=1002,
                             aboveNormal=1003,
                             timeCritical=1004,
                             minPriority=1000,
                             maxPriority=1004 }

  These values represent the portable thread priority levels available to set via setThreadPriority().

Supported Platforms

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

### INonGUIThread - Type Definitions

( unsigned long )

      typedef void ( _System * SystemFnPtr ) ( unsigned long )

  This typedef defines a pointer to a function that uses the _System calling convention.
  Note: _System is the default calling convention for the OS/2 operating system.

Supported Platforms

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

( void * )

      typedef void ( _Optlink * OptlinkFnPtr ) ( void * )

  This typedef defines a pointer to a function that uses the _Optlink calling convention.
  Note: _Optlink is the default calling convention for &CSET..

Supported Platforms

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

### INonGUIThread - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  INonGUIThread

  -     static IStartedThread* newStartedThread()

  -     INonGUIThread& operator =(const INonGUIThread& thread)

  -     virtual IStartedThread* startedThread() const

#### Inherited Protected Data

  - None