DosEnterCritSec

Disables thread switching for the current process.

Syntax

DosEnterCritSec ()

Parameters

none

Return Code

ulrc (APIRET) - returns

DosEnterCritSec returns one of the following values:

• 0 NO_ERROR
• 309 ERROR_INVALID_THREADID
• 484 ERROR_CRITSEC_OVERFLOW

Remarks

DosEnterCritSec causes all other threads in the process to block themselves and give up their time slice. After a DosEnterCritSec request is made, no functions should be called that depend on another thread to do processing until DosExitCritSec has completed. Great care should be taken when using compiler runtime functions and other OS/2 functions after a DosEnterCritSec request has been made, since the underlying processing of the called function may require processing by another thread and thus cause a deadlock.

A thread can also execute code without having to give up time slices to other threads in its process if it requests a priority class that is higher than those of the other threads. A thread's priority is examined with DosGetInfoBlocks, and changed with DosSetPriority.

A count is maintained of the number of times DosEnterCritSec is issued without a corresponding DosExitCritSec. The count is incremented by DosEnterCritSec and decremented by DosExitCritSec. Normal thread dispatching is not restored until the count is zero. The outstanding DosEnterCritSec count is maintained in a word. If an overflow occurs, the count is set to the maximum value, no operation is performed, and the request returns with ERROR_CRITSEC_OVERFLOW.

If a signal occurs, thread 1 begins execution to process the signal even though another thread in the process has a DosEnterCritSec active. Thread 1 of a process is its initial thread of execution, not a thread created with DosCreateThread. Any processing done by thread 1 to satisfy the signal must not include accessing the critical resource intended to be protected by DosEnterCritSec.

Note: This function is very powerful and must be used with caution! It should be used only in a most cooperative environment where the state of all threads in known. While in the critical section, do not call other compiler runtime or OS/2 functions that could start another thread that it would depend on running before being able to return.

DosQueryThreadContext can be used to obtain the context of other threads in the process once they have been blocked by DosEnterCritSec.

ERROR_INVALID_THREADID is returned when an invalid attempt is made to enter a critical section of code in a signal handler or exception handler.

ERROR_INVALID_THREADID is also returned when a dynamic link library (DLL) routine incorrectly issues DosEnterCritSec.

Example Code

This example shows how a thread enters and exits a critical section of code.

#define INCL_DOSPROCESS      /* Process values */
#define INCL_DOSERRORS       /* Error values */
#include <os2.h>
#include <stdio.h>

int main(VOID)
  {
  APIRET  rc = NO_ERROR;    /* Return code */

   rc = DosEnterCritSec();

   if (rc != NO_ERROR) {
       printf("DosEnterCritSec error: return code = %u\n",rc);
       return 1;
   }
     /***********************************************/
     /* Add critical section code here.  While this */
     /* code is running, all other threads are      */
     /* stopped.  CALL NO LIBRARY OR OS/2 FUNCTIONS */
     /* HERE UNLESS YOU KNOW THEY DO NOT REQUIRE    */
     /* ACTION BY ANOTHER THREAD IN THE PROCESS.    */
     /***********************************************/

   rc =  DosExitCritSec();

   if (rc != NO_ERROR) {
       printf("DosExitCritSec error: return code = %u\n",rc);
       return 1;
   }

   return NO_ERROR;
   }

Related Functions

• DosCreateThread
• DosExitCritSec
• DosQueryThreadContext