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:

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.


[view 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


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


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


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


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

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

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


[view 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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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

Inherited Public Data

Inherited Protected Functions

INonGUIThread

Inherited Protected Data