DosSuspendThread

Description

Temporarily suspends processing of another thread within the current process until DosResumeThread is issued.

Syntax

#define INCL_DOSPROCESS
#include <os2.h>

TID       tid;   /*  Thread identifier of the thread to be suspended. */
APIRET    ulrc;  /*  Return Code. */

ulrc = DosSuspendThread(tid);

Parameters

tid (TID) - input

Thread identifier of the thread to be suspended.

Return Code

ulrc (APIRET) - returns

DosSuspendThread returns one of the following values:

• 0 NO_ERROR
• 309 ERROR_INVALID_THREADID

Remarks

A thread's execution is suspended when another thread in its process issues DosSuspendThread, specifying the ID of the target thread. The thread may not be suspended immediately because it may have locked some system resources that have to be freed first. However, the thread is not allowed to execute further application program instructions until a corresponding DosResumeThread is issued.

DosSuspendThread permits the suspension of only one other thread within the current process. If a thread needs to disable all thread switching within its process so that the calling thread can execute time-critical code, it issues DosEnterCritSec and DosExitCritSec.

DosKillThread will not terminate a thread that is suspended. Instead the suspended thread will be terminated when it resumes execution. For this reason, you should not kill the main thread of an application if there are any secondary threads that are suspended.

Note: This function is very powerful and must be used with extreme caution. It should be used only when the state of the target thread is known.

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 IBM CSet/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

• DosCreateThread
• DosEnterCritSec
• DosResumeThread