BeginThreadGroup

Establishes a new thread within a new thread group

Local Servers:blocking
Remote Servers:N/A
Classification:3.x, 4.x, 5.x, 6.x
Service:Thread

Syntax

  #include <nwthread.h>  
   
  int BeginThreadGroup  (  
     void       (*func) (void*),  
     void       *stack,   
     unsigned    stackSize,   
     void       *arg);

Parameters

func
(IN) Points to the function to execute as the new thread.
stack
(IN) Points to a block of memory to use for the new thread’s stack.
stackSize
(IN) Specifies the size (in bytes) of the stack.
arg
(IN) Points to an argument to be passed to the new thread.

Return Values

This function returns the new thread group’s ID if successful. It returns EFAILURE if an error occurs.

If an error occurs, errno is set to:

Value

Name

Description

5

ENOMEM

Not enough memory.

9

EINVAL

Invalid argument was passed in.

Remarks

The BeginThreadGroup function creates a new thread group which contains one thread defined by func. Other than putting the new thread in its own thread group, this function is identical to BeginThread. A thread group can consist of one or more threads as defined by the programmer, and an NLM can have more than one thread group.

The new thread group is not the current thread group. To create more threads within the new thread group, you must make the new thread group current by calling SetThreadGroupID with the thread group ID returned by BeginThreadGroup. You can then create more threads within the new thread group by calling BeginThread for each additional thread for the new thread group.

The new thread begins execution at the specified function ( func). The function func receives arg as a parameter. The stack parameter is a pointer to a block of memory that the new thread uses as its stack.

  • If stack is NULL, a block of memory (as specified by the stackSize parameter) is allocated.
  • If stack is NULL and the specified stack size is too small, the size for the new thread stack is increased automatically.
  • If stack is not NULL and the specified stack size is too small, the function fails and errno is set to EINVAL. The minimum stack size for the 3.x OS is 2,064 bytes and 8,192 bytes for the 4.x, 5.x, and 6.x OS.
  • If stackSize is zero and stack is NULL, then the default stack size (8,192 bytes for 3.x and for 4.x, 5.x, and 6.x) is used.

The arg parameter is any 32-bit quantity, although typically some sort of pointer is passed, or NULL is passed if the specified function does not take any arguments.

If the newly created thread returns from the function func, it is be equivalent to its having executed the ExitThread function with an action code of EXIT_THREAD.

See Also

BeginThread

Example

  #include <nwthread.h>  
  #include <stdio.h>  
   
  void newThreadFunc (char *funcArg);  
  int   completionCode;  
  .  
  .  
  .  
  completionCode = BeginThreadGroup (newThreadFunc, NULL, 8192, "/A/Q
      input.fil");  
  .  
  .  
  .  
  void newThreadFunc(char *arg)  
  {  
     printf ("in new thread group\n");  
  }