Man Linux: Main Page and Category List

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 .