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.

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;
}

Related Functions