Thread Manager
**************

Introduction
============

The thread manager ...

The directives provided by the thread manager are:

  * pthread_attr_init -

  * pthread_attr_destroy -

  * pthread_attr_setdetachstate -

  * pthread_attr_getdetachstate -

  * pthread_attr_setstacksize -

  * pthread_attr_getstacksize -

  * pthread_attr_setstackaddr -

  * pthread_attr_getstackaddr -

  * pthread_attr_setscope -

  * pthread_attr_getscope -

  * pthread_attr_setinheritsched -

  * pthread_attr_getinheritsched -

  * pthread_attr_setschedpolicy -

  * pthread_attr_getschedpolicy -

  * pthread_attr_setschedparam -

  * pthread_attr_getschedparam -

  * pthread_create -

  * pthread_exit -

  * pthread_detach -

  * pthread_join -

  * pthread_self -

  * pthread_equal -

  * pthread_once -

  * pthread_setschedparam -

  * pthread_getschedparam -

Background
==========

Thread Attributes
-----------------

Thread attributes are utilized only at thread creation time.

stack address
     is the address of the optionally user specified stack area for this thread. If this value is NULL, then RTEMS allocates the memory for the thread stack from the RTEMS Workspace Area.  Otherwise, this is the user specified address for the memory to be used for the thread's stack.  Each thread must have a distinct stack area.  Each processor family has different alignment rules which should be followed.

stack size
     is the minimum desired size for this thread's stack area. If the size of this area as specified by the stack size attribute is smaller than the minimum for this processor family and the stack is not user specified, then RTEMS will automatically allocate a stack of the minimum size for this processor family.

contention scope
     specifies the scheduling contention scope.  RTEMS only supports the PTHREAD_SCOPE_PROCESS scheduling contention scope.

scheduling inheritance
     specifies whether a user specified or the scheduling policy and parameters of the currently executing thread are to be used.  When this is PTHREAD_INHERIT_SCHED, then the scheduling policy and parameters of the currently executing thread are inherited by the newly created thread.

scheduling policy and parameters
     specify the manner in which the thread will contend for the processor. The scheduling parameters are interpreted based on the specified policy. All policies utilize the thread priority parameter.

Operations
==========

Directives
==========

This section details the thread manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes.

pthread_attr_init
-----------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_init(
       pthread_attr_t  *attr
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_destroy
--------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_destroy(
       pthread_attr_t  *attr
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setdetachstate
---------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setdetachstate(
       pthread_attr_t  *attr,
       int              detachstate
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The detachstate argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getdetachstate
---------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getdetachstate(
       const pthread_attr_t  *attr,
       int                   *detachstate
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The detatchstate pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setstacksize
-------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setstacksize(
       pthread_attr_t  *attr,
       size_t           stacksize
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

DESCRIPTION:
------------

NOTES:
------

If the specified stacksize is below the minimum required for this CPU, then the stacksize will be set to the minimum for this CPU.

pthread_attr_getstacksize
-------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getstacksize(
       const pthread_attr_t  *attr,
       size_t                *stacksize
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The stacksize pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setstackaddr
-------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setstackaddr(
       pthread_attr_t  *attr,
       void            *stackaddr
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getstackaddr
-------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getstackaddr(
       const pthread_attr_t  *attr,
       void                 **stackaddr
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The stackaddr pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setscope
---------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setscope(
       pthread_attr_t  *attr,
       int              contentionscope
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The contention scope specified is not valid.

ENOTSUP
     The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getscope
---------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getscope(
       const pthread_attr_t  *attr,
       int                   *contentionscope
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The contentionscope pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setinheritsched
----------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setinheritsched(
       pthread_attr_t  *attr,
       int              inheritsched
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The specified scheduler inheritance argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getinheritsched
----------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getinheritsched(
       const pthread_attr_t  *attr,
       int                   *inheritsched
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The inheritsched pointer argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setschedpolicy
---------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setschedpolicy(
       pthread_attr_t  *attr,
       int              policy
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

ENOTSUP
     The specified scheduler policy argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getschedpolicy
---------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getschedpolicy(
       const pthread_attr_t  *attr,
       int                   *policy
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The specified scheduler policy argument pointer is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_setschedparam
--------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_setschedparam(
       pthread_attr_t            *attr,
       const struct sched_param   param
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The specified scheduler parameter argument is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_attr_getschedparam
--------------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_attr_getschedparam(
       const pthread_attr_t  *attr,
       struct sched_param    *param
     );

STATUS CODES:
-------------

EINVAL
     The attribute pointer argument is invalid.

EINVAL
     The attribute set is not initialized.

EINVAL
     The specified scheduler parameter argument pointer is invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_create
--------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

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

STATUS CODES:
-------------

EINVAL
     The attribute set is not initialized.

EINVAL
     The user specified a stack address and the size of the area was not large enough to meet this processor's minimum stack requirements.

EINVAL
     The specified scheduler inheritance policy was invalid.

ENOTSUP
     The specified contention scope was PTHREAD_SCOPE_PROCESS.

EINVAL
     The specified thread priority was invalid.

EINVAL
     The specified scheduling policy was invalid.

EINVAL
     The scheduling policy was SCHED_SPORADIC and the specified replenishment period is less than the initial budget.

EINVAL
     The scheduling policy was SCHED_SPORADIC and the specified low priority is invalid.

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

EINVAL
     Invalid argument passed.

DESCRIPTION:
------------

NOTES:
------

pthread_exit
------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     void pthread_exit(
       void   *status
     );

STATUS CODES:
-------------

NONE

DESCRIPTION:
------------

NOTES:
------

pthread_detach
--------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_detach(
       pthread_t   thread
     );

STATUS CODES:
-------------

ESRCH
     The thread specified is invalid.

EINVAL
     The thread specified is not a joinable thread.

DESCRIPTION:
------------

NOTES:
------

If any threads have previously joined with the specified thread, then they will remain joined with that thread.  Any subsequent calls to pthread_join on the specified thread will fail.

pthread_join
------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_join(
       pthread_t   thread,
       void      **value_ptr
     );

STATUS CODES:
-------------

ESRCH
     The thread specified is invalid.

EINVAL
     The thread specified is not a joinable thread.

EDEADLK
     A deadlock was detected or thread is the calling thread.

DESCRIPTION:
------------

NOTES:
------

If any threads have previously joined with the specified thread, then they will remain joined with that thread.  Any subsequent calls to pthread_join on the specified thread will fail.

If value_ptr is NULL, then no value is returned.

pthread_self
------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     pthread_t pthread_self( void );

STATUS CODES:
-------------

This routine returns the id of the calling thread.

DESCRIPTION:
------------

NOTES:
------

pthread_equal
-------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_equal(
       pthread_t  t1,
       pthread_t  t2
     );

STATUS CODES:
-------------

zero
     The thread ids are not equal.

non-zero
     The thread ids are equal.

DESCRIPTION:
------------

NOTES:
------

The behavior is undefined if the thread IDs are not valid.

pthread_once
------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     pthread_once_t once_control = PTHREAD_ONCE_INIT;

     int pthread_once(
       pthread_once_t  *once_control,
       void           (*init_routine)(void)
     );

STATUS CODES:
-------------

NONE

DESCRIPTION:
------------

NOTES:
------

pthread_setschedparam
---------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_setschedparam(
       pthread_t           thread,
       int                 policy,
       struct sched_param *param
     );

STATUS CODES:
-------------

EINVAL
     The scheduling parameters indicated by the parameter param is invalid.

EINVAL
     The value specified by policy is invalid.

EINVAL
     The scheduling policy was SCHED_SPORADIC and the specified replenishment period is less than the initial budget.

EINVAL
     The scheduling policy was SCHED_SPORADIC and the specified low priority is invalid.

ESRCH
     The thread indicated was invalid.

DESCRIPTION:
------------

NOTES:
------

pthread_getschedparam
---------------------

CALLING SEQUENCE:
-----------------

     #include <pthread.h>

     int pthread_getschedparam(
       pthread_t           thread,
       int                *policy,
       struct sched_param *param
     );

STATUS CODES:
-------------

EINVAL
     The policy pointer argument is invalid.

EINVAL
     The scheduling parameters pointer argument is invalid.

ESRCH
     The thread indicated by the parameter thread is invalid.

DESCRIPTION:
------------

NOTES:
------