### _beginthread -- Create New Thread

Format

>     #include <stdlib.h>   /* also in <process.h> */
>     int _beginthread(void (*start_address) (void *),
>                          (void *)stack,
>                          unsigned stack_size,
>                          void *arglist);

Language Level: Extension
_beginthread creates a new thread. It takes the following arguments:

start_address
This parameter is the address of the function that the newly created thread will execute. When the thread returns from that function, it is terminated automatically. You can also explicitly terminate the thread by calling _endthread.

stack
This parameter is ignored. It is retained for compatibility with other compilers.

stack_size
The size of the stack, in bytes, that is to be allocated for the new thread. The stack size should be a nonzero multiple of 4K and a minimum of 8K. Memory is used when needed, one page at a time.

arglist
A parameter to be passed to the newly created thread. It is the size of a pointer, and is usually the address of a data item to be passed to the new thread, such as a char string. It provides _beginthread with a value to pass to the child thread. NULL can be used as a placeholder.

The function that the new thread will perform must be declared and compiled using _Optlink linkage.

An alternative to this function, on OS/2, is the DosCreateThread API.

On Windows, an alternative to this function is the Win32 CreateThread API.

If you use the OS/2 DosCreateThread or the Win32 CreateThread API, you must also use a #pragma handler statement for the thread function to ensure proper C exception handling. You should also call the _fpreset function at the start of the thread to preset the 387 control status word correctly.

Using the OS/2 DosCreateThread API or the Win32 CreateThread API requires that you use _endthread to terminate the thread. Otherwise, your program will leak memory.

Note: When using the _beginthread and _endthread functions, you must specify the /Gm+ compiler option to use the multithread libraries.

Return Value
If successful, _beginthread returns the thread handle of the new thread. It returns -1 to indicate an error.

Example
This example uses _beginthread to start a new thread bonjour.

Note: To run this example, you must compile it using the /Gm+ compiler option.

    #if  (1 == __TOS_OS2__)
         #define INCL_DOS                                /* OS/2 */
         #include <os2.h>
         #define SLEEP  DosSleep(0l)
    #else
         #include <windows.h>                            /* Windows */
         #define SLEEP  Sleep(0l)
    #endif

    #include <stdio.h>
    #include <stdlib.h>

    static volatile int wait = 1;

    void _Optlink bonjour(void *arg)
    {
       int i = 0;

       while (wait)               /* wait until the thread id has been printed     */
            SLEEP;
       while (i++ <5)
          printf("Bonjour!\n");

    }

    int main(void)
    {
       int tid;

       tid = _beginthread(bonjour, NULL, 8192, NULL);
       if (-1 == tid) {
          printf("Unable to start thread.\n");
          return EXIT_FAILURE;
       }
       else {
          printf("Thread started with thread identifier number %d.\n", tid);
          wait = 0;
       }
    #if  (1 == __TOS_OS2__)
      DosWaitThread((PTID)&tid, DCWW_WAIT);  /* wait for thread bonjour to end    */
                                             /* before ending main thread         */
    #else
      WaitForSingleObject((HANDLE)tid, INFINITE); /* wait for thread bonjour to end */
                                                  /*  before ending main thread     */
    #endif

       return 0;

       /****************************************************************************
          The output should be similar to:

           Thread started with thread identifier number 2.
           Bonjour!
           Bonjour!
           Bonjour!
           Bonjour!
           Bonjour!
       ****************************************************************************/
    }

_endthread -- Terminate Current Thread
_threadstore -- Access Thread-Specific Storage
<stdlib.h>
<process.h>
/Gm compiler option