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 |
- 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
Inherited Public Data
Inherited Protected Functions
- INonGUIThread
-
static IStartedThread* newStartedThread()
INonGUIThread& operator =(const INonGUIThread& thread)
virtual IStartedThread* startedThread() const
Inherited Protected Data