DosWaitThread
Places the current thread into a wait state until another thread in the current process has ended. It then returns the thread identifier of the ending thread.
Syntax
DosWaitThread(ptid, option)
Parameters
- ptid (PTID) - in/out
- Address of the thread identification.
- Input: The address of the ThreadID of the thread of interest. If ptid is 0, the current thread waits until the next thread in the process has ended. If ptid is nonzero, the current thread waits until the indicated thread has ended.
- Output: The ThreadID of the ended thread is returned in this field.
- option (ULONG) - input
- An indicator that specifies whether to return if no thread has ended.
- The values of this field are shown in the following list:
- 0 DCWW_WAIT
- The current thread waits until a thread ends. If a thread has already ended, the call returns immediately with the ptid.
- 1 DCWW_NOWAIT
- The current thread does not wait if no threads have ended.
- 0 DCWW_WAIT
Return Code
- ulrc (APIRET) - returns
- DosWaitThread returns one of the following values:
- 0 NO_ERROR
- 95 ERROR_INTERRUPT
- 294 ERROR_THREAD_NOT_TERMINATED
- 309 ERROR_INVALID_THREADID
Remarks
DosWaitThread is used to wait for termination of threads within a process. It is usually used so that thread resources (for example, the stack) can be recovered when a thread ends. DosWaitThread waits on any thread within the current process, or on a specific thread within the process, based on the ptid parameter's contents. option allows the caller the option of waiting until a thread ends, or getting immediate return and status. If no thread has ended and the DCWW_NOWAIT option is specified, the ptid field is preserved.
If DosWaitThread is called with the input ptid set to the current thread (the thread attempts to wait on its own termination), the ERROR_INVALID_THREADID error code is returned. ERROR_INVALID_THREADID is also returned if a caller attempts to wait on the termination of the thread with a ptid of 1.
Example Code
This example creates a new thread within a process, sleeps for 1 second, suspends the thread for 5 seconds, and then waits for the thread to terminate.
Compile this example with MULTITHREAD LIBRARIES. If you are using C Set/2, use the /Gm+ switch.
#define INCL_DOSPROCESS /* Process and thread values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
void _System CntThreadProc(ULONG LoopMax); /* Count Thread */
int main(VOID) {
TID tidCntThread = 0; /* ID returned for newly created thread */
PFNTHREAD pfnCntThread = &CntThreadProc; /* Address of thread program */
ULONG ulThreadParm = 100; /* Parameter to thread routine */
APIRET rc = NO_ERROR; /* Return code */
rc = DosCreateThread(&tidCntThread, /* Thread ID (returned by function) */
pfnCntThread, /* Address of thread program */
ulThreadParm, /* Parameter passed to ThreadProc */
CREATE_READY | /* Thread is ready when created */
STACK_SPARSE, /* Do not pre-commit stack pages */
8192L); /* Stack size, rounded to page bdy */
if (rc != NO_ERROR) {
printf("DosCreateThread error: return code = %u\n", rc);
return 1;
}
rc = DosSleep (1000); /* Sleep for a second to allow thread to run a bit */
rc = DosSuspendThread (tidCntThread);
if (rc != NO_ERROR) {
printf("DosSuspendThread error: return code = %u\n", rc);
return 1;
}
rc = DosSleep (5000); /* Sleep 5 seconds before resuming the thread */
rc = DosResumeThread (tidCntThread);
if (rc != NO_ERROR) {
printf("DosResumeThread error: return code = %u\n", rc);
return 1;
}
rc = DosWaitThread (&tidCntThread, DCWW_WAIT);
if (rc != NO_ERROR) {
printf ("DosWaitThread error : return code = %u\n", rc);
}
printf ("Thread has completed!\n");
return NO_ERROR;
}
void _System CntThreadProc(ULONG LoopMax ) /* Count thread */
{
ULONG i = 0; /* Loop index */
for (i=0;i < LoopMax;i++ ) {
printf ("%d\n", i);
}
return;
}