trusty (3) pthread_create.3posix.gz

NAME

       pthread_create - thread creation

SYNOPSIS

       #include <pthread.h>

       int pthread_create(pthread_t *restrict thread,
              const pthread_attr_t *restrict attr,
              void *(*start_routine)(void*), void *restrict arg);

DESCRIPTION

       The  pthread_create()  function  shall  create  a new thread, with attributes specified by attr, within a
       process. If attr is NULL, the default attributes shall be used. If the attributes specified by  attr  are
       modified   later,   the   thread's   attributes  shall  not  be  affected.  Upon  successful  completion,
       pthread_create() shall store the ID of the created thread in the location referenced by thread.

       The thread is created executing start_routine with  arg  as  its  sole  argument.  If  the  start_routine
       returns, the effect shall be as if there was an implicit call to pthread_exit() using the return value of
       start_routine as the exit status. Note that the thread in which main()  was  originally  invoked  differs
       from  this.  When  it returns from main(), the effect shall be as if there was an implicit call to exit()
       using the return value of main() as the exit status.

       The signal state of the new thread shall be initialized as follows:

        * The signal mask shall be inherited from the creating thread.

        * The set of signals pending for the new thread shall be empty.

       The alternate stack shall not be inherited.

       The floating-point environment shall be inherited from the creating thread.

       If pthread_create() fails, no new thread is created and the contents of the location referenced by thread
       are undefined.

       If  _POSIX_THREAD_CPUTIME  is  defined,  the  new  thread shall have a CPU-time clock accessible, and the
       initial value of this clock shall be set to zero.

RETURN VALUE

       If successful, the pthread_create() function shall return zero;  otherwise,  an  error  number  shall  be
       returned to indicate the error.

ERRORS

       The pthread_create() function shall fail if:

       EAGAIN The system lacked the necessary resources to create another thread, or the system-imposed limit on
              the total number of threads in a process {PTHREAD_THREADS_MAX} would be exceeded.

       EINVAL The value specified by attr is invalid.

       EPERM  The caller does not have appropriate permission to  set  the  required  scheduling  parameters  or
              scheduling policy.

       The pthread_create() function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       A suggested alternative to pthread_create() would be to define two separate operations: create and start.
       Some applications would find such behavior more natural. Ada, in particular, separates the "creation"  of
       a task from its "activation".

       Splitting the operation was rejected by the standard developers for many reasons:

        * The  number  of  calls  required  to  start  a thread would increase from one to two and thus place an
          additional burden on applications that do not require the additional synchronization. The second call,
          however, could be avoided by the additional complication of a start-up state attribute.

        * An  extra  state  would  be  introduced: "created but not started". This would require the standard to
          specify the behavior of the thread operations when the target has not yet started executing.

        * For those applications that require such behavior, it is possible to simulate the two  separate  steps
          with  the  facilities that are currently provided. The start_routine() can synchronize by waiting on a
          condition variable that is signaled by the start operation.

       An Ada implementor can choose to create the thread at either of two points in the Ada program:  when  the
       task  object is created, or when the task is activated (generally at a "begin"). If the first approach is
       adopted, the start_routine() needs to wait on  a  condition  variable  to  receive  the  order  to  begin
       "activation".   The  second  approach  requires  no  such condition variable or extra synchronization. In
       either approach, a separate Ada task control block would need to be  created  when  the  task  object  is
       created to hold rendezvous queues, and so on.

       An  extension of the preceding model would be to allow the state of the thread to be modified between the
       create and start. This would allow the thread attributes object to be eliminated. This has been  rejected
       because:

        * All  state in the thread attributes object has to be able to be set for the thread. This would require
          the definition of functions to modify thread attributes. There would be no reduction in the number  of
          function  calls  required  to set up the thread.  In fact, for an application that creates all threads
          using identical attributes, the number of function calls required to  set  up  the  threads  would  be
          dramatically  increased.  Use of a thread attributes object permits the application to make one set of
          attribute setting function calls. Otherwise, the set of attribute setting function calls needs  to  be
          made for each thread creation.

        * Depending  on  the  implementation  architecture,  functions  to set thread state would require kernel
          calls, or for other implementation reasons would not be able to  be  implemented  as  macros,  thereby
          increasing the cost of thread creation.

        * The ability for applications to segregate threads by class would be lost.

       Another  suggested  alternative uses a model similar to that for process creation, such as "thread fork".
       The fork semantics would provide more flexibility and the "create" function can be implemented simply  by
       doing  a  thread  fork followed immediately by a call to the desired "start routine" for the thread. This
       alternative has these problems:

        * For many implementations, the entire stack of the calling thread would need to be duplicated, since in
          many architectures there is no way to determine the size of the calling frame.

        * Efficiency  is  reduced  since  at  least some part of the stack has to be copied, even though in most
          cases the thread never needs the copied context, since it merely calls the desired start routine.

FUTURE DIRECTIONS

       None.

SEE ALSO

       fork() ,  pthread_exit()  ,  pthread_join()  ,  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc and The Open Group. In the event of any discrepancy between this version and the  original  IEEE  and
       The  Open  Group  Standard,  the  original  IEEE and The Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .