From 1264a8f1089fad85cabb024c930b19b0a36864b4 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 00:55:21 -0500 Subject: Split document into seperate files by section. --- posix_users/thread.rst | 1333 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1333 insertions(+) create mode 100644 posix_users/thread.rst (limited to 'posix_users/thread.rst') diff --git a/posix_users/thread.rst b/posix_users/thread.rst new file mode 100644 index 0000000..4bd80ed --- /dev/null +++ b/posix_users/thread.rst @@ -0,0 +1,1333 @@ +Thread Manager +############## + +Introduction +============ + +The thread manager implements the functionality required of the thread +manager as defined by POSIX 1003.1b. This standard requires that +a compliant operating system provide the facilties to manage multiple +threads of control and defines the API that must be provided. + +The services provided by the thread manager are: + +- ``pthread_attr_init`` - Initialize a Thread Attribute Set + +- ``pthread_attr_destroy`` - Destroy a Thread Attribute Set + +- ``pthread_attr_setdetachstate`` - Set Detach State + +- ``pthread_attr_getdetachstate`` - Get Detach State + +- ``pthread_attr_setstacksize`` - Set Thread Stack Size + +- ``pthread_attr_getstacksize`` - Get Thread Stack Size + +- ``pthread_attr_setstackaddr`` - Set Thread Stack Address + +- ``pthread_attr_getstackaddr`` - Get Thread Stack Address + +- ``pthread_attr_setscope`` - Set Thread Scheduling Scope + +- ``pthread_attr_getscope`` - Get Thread Scheduling Scope + +- ``pthread_attr_setinheritsched`` - Set Inherit Scheduler Flag + +- ``pthread_attr_getinheritsched`` - Get Inherit Scheduler Flag + +- ``pthread_attr_setschedpolicy`` - Set Scheduling Policy + +- ``pthread_attr_getschedpolicy`` - Get Scheduling Policy + +- ``pthread_attr_setschedparam`` - Set Scheduling Parameters + +- ``pthread_attr_getschedparam`` - Get Scheduling Parameters + +- ``pthread_attr_getaffinity_np`` - Get Thread Affinity Attribute + +- ``pthread_attr_setaffinity_np`` - Set Thread Affinity Attribute + +- ``pthread_create`` - Create a Thread + +- ``pthread_exit`` - Terminate the Current Thread + +- ``pthread_detach`` - Detach a Thread + +- ``pthread_getattr_np`` - Get Thread Attributes + +- ``pthread_join`` - Wait for Thread Termination + +- ``pthread_self`` - Get Thread ID + +- ``pthread_equal`` - Compare Thread IDs + +- ``pthread_once`` - Dynamic Package Initialization + +- ``pthread_setschedparam`` - Set Thread Scheduling Parameters + +- ``pthread_getschedparam`` - Get Thread Scheduling Parameters + +- ``pthread_getaffinity_np`` - Get Thread Affinity + +- ``pthread_setaffinity_np`` - Set Thread Affinity + +Background +========== + +Thread Attributes +----------------- + +Thread attributes are utilized only at thread creation time. A thread +attribute structure may be initialized and passed as an argument to +the ``pthread_create`` routine. + +*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 +========== + +There is currently no text in this section. + +Services +======== + +This section details the thread manager’s services. +A subsection is dedicated to each of this manager’s services +and describes the calling sequence, related constants, usage, +and status codes. + +pthread_attr_init - Initialize a Thread Attribute Set +----------------------------------------------------- +.. index:: pthread_attr_init +.. index:: initialize a thread attribute set + +**CALLING SEQUENCE:** + +.. code:: c + + #include + int pthread_attr_init( + pthread_attr_t \*attr + ); + +**STATUS CODES:** + +*EINVAL* + The attribute pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_attr_init`` routine initializes the thread attributes +object specified by ``attr`` with the default value for all of the +individual attributes. + +**NOTES:** + +The settings in the default attributes are implementation defined. For +RTEMS, the default attributes are as follows: + +- stackadr + is not set to indicate that RTEMS is to allocate the stack memory. + +- stacksize + is set to ``PTHREAD_MINIMUM_STACK_SIZE``. + +- contentionscope + is set to ``PTHREAD_SCOPE_PROCESS``. + +- inheritsched + is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created + thread inherits its scheduling attributes from its parent. + +- detachstate + is set to ``PTHREAD_CREATE_JOINABLE``. + +pthread_attr_destroy - Destroy a Thread Attribute Set +----------------------------------------------------- +.. index:: pthread_attr_destroy +.. index:: destroy a thread attribute set + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_destroy`` routine is used to destroy a thread +attributes object. The behavior of using an attributes object after +it is destroyed is implementation dependent. + +**NOTES:** + +NONE + +pthread_attr_setdetachstate - Set Detach State +---------------------------------------------- +.. index:: pthread_attr_setdetachstate +.. index:: set detach state + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setdetachstate`` routine is used to value of the``detachstate`` attribute. This attribute controls whether the +thread is created in a detached state. + +The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or``PTHREAD_CREATE_JOINABLE``. The default value for all threads is``PTHREAD_CREATE_JOINABLE``. + +**NOTES:** + +If a thread is in a detached state, +then the use of the ID with the ``pthread_detach`` or``pthread_join`` routines is an error. + +pthread_attr_getdetachstate - Get Detach State +---------------------------------------------- +.. index:: pthread_attr_getdetachstate +.. index:: get detach state + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getdetachstate`` routine is used to obtain the +current value of the ``detachstate`` attribute as specified +by the ``attr`` thread attribute object. + +**NOTES:** + +NONE + +pthread_attr_setstacksize - Set Thread Stack Size +------------------------------------------------- +.. index:: pthread_attr_setstacksize +.. index:: set thread stack size + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setstacksize`` routine is used to set the``stacksize`` attribute in the ``attr`` thread attribute +object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this +routine is supported. + +If the specified stacksize is below the minimum required for this CPU +(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum +for this CPU. + +pthread_attr_getstacksize - Get Thread Stack Size +------------------------------------------------- +.. index:: pthread_attr_getstacksize +.. index:: get thread stack size + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getstacksize`` routine is used to obtain the``stacksize`` attribute in the ``attr`` thread attribute +object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this +routine is supported. + +pthread_attr_setstackaddr - Set Thread Stack Address +---------------------------------------------------- +.. index:: pthread_attr_setstackaddr +.. index:: set thread stack address + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setstackaddr`` routine is used to set the``stackaddr`` attribute in the ``attr`` thread attribute +object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this +routine is supported. + +It is imperative to the proper operation of the system that +each thread have sufficient stack space. + +pthread_attr_getstackaddr - Get Thread Stack Address +---------------------------------------------------- +.. index:: pthread_attr_getstackaddr +.. index:: get thread stack address + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getstackaddr`` routine is used to obtain the``stackaddr`` attribute in the ``attr`` thread attribute +object. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this +routine is supported. + +pthread_attr_setscope - Set Thread Scheduling Scope +--------------------------------------------------- +.. index:: pthread_attr_setscope +.. index:: set thread scheduling scope + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setscope`` routine is used to set the contention +scope field in the thread attribute object ``attr`` to the value +specified by ``contentionscope``. + +The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM`` +to indicate that the thread is to be within system scheduling contention +or ``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be +within the process scheduling contention scope. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_getscope - Get Thread Scheduling Scope +--------------------------------------------------- +.. index:: pthread_attr_getscope +.. index:: get thread scheduling scope + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getscope`` routine is used to obtain the +value of the contention scope field in the thread attributes +object ``attr``. The current value is returned in``contentionscope``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_setinheritsched - Set Inherit Scheduler Flag +--------------------------------------------------------- +.. index:: pthread_attr_setinheritsched +.. index:: set inherit scheduler flag + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setinheritsched`` routine is used to set the +inherit scheduler field in the thread attribute object ``attr`` to +the value specified by ``inheritsched``. + +The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED`` +to indicate that the thread is to inherit the scheduling policy +and parameters fromthe creating thread, or ``PTHREAD_EXPLICIT_SCHED`` +to indicate that the scheduling policy and parameters for this thread +are to be set from the corresponding values in the attributes object. +If ``contentionscope`` is ``PTHREAD_INHERIT_SCHED``, then the +scheduling attributes in the ``attr`` structure will be ignored +at thread creation time. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_getinheritsched - Get Inherit Scheduler Flag +--------------------------------------------------------- +.. index:: pthread_attr_getinheritsched +.. index:: get inherit scheduler flag + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getinheritsched`` routine is used to +object the current value of the inherit scheduler field in +the thread attribute object ``attr``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_setschedpolicy - Set Scheduling Policy +--------------------------------------------------- +.. index:: pthread_attr_setschedpolicy +.. index:: set scheduling policy + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setschedpolicy`` routine is used to set the +scheduler policy field in the thread attribute object ``attr`` to +the value specified by ``policy``. + +Scheduling policies may be one of the following: + +- ``SCHED_DEFAULT`` + +- ``SCHED_FIFO`` + +- ``SCHED_RR`` + +- ``SCHED_SPORADIC`` + +- ``SCHED_OTHER`` + +The precise meaning of each of these is discussed elsewhere in this +manual. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_getschedpolicy - Get Scheduling Policy +--------------------------------------------------- +.. index:: pthread_attr_getschedpolicy +.. index:: get scheduling policy + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getschedpolicy`` routine is used to obtain the +scheduler policy field from the thread attribute object ``attr``. +The value of this field is returned in ``policy``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_setschedparam - Set Scheduling Parameters +------------------------------------------------------ +.. index:: pthread_attr_setschedparam +.. index:: set scheduling parameters + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_setschedparam`` routine is used to set the +scheduler parameters field in the thread attribute object ``attr`` to +the value specified by ``param``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_getschedparam - Get Scheduling Parameters +------------------------------------------------------ +.. index:: pthread_attr_getschedparam +.. index:: get scheduling parameters + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_attr_getschedparam`` routine is used to obtain the +scheduler parameters field from the thread attribute object ``attr``. +The value of this field is returned in ``param``. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_attr_getaffinity_np - Get Thread Affinity Attribute +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code:: c + + #define _GNU_SOURCE + #include + int pthread_attr_getaffinity_np( + const pthread_attr_t \*attr, + size_t cpusetsize, + cpu_set_t \*cpuset + ); + +**STATUS CODES:** + +*EFAULT* + The attribute pointer argument is invalid. + +*EFAULT* + The cpuset pointer argument is invalid. + +*EINVAL* + The ``cpusetsize`` does not match the value of ``affinitysetsize`` + field in the thread attribute object. + +**DESCRIPTION:** + +The ``pthread_attr_getaffinity_np`` routine is used to obtain the``affinityset`` field from the thread attribute object ``attr``. +The value of this field is returned in ``cpuset``. + +**NOTES:** + +NONE + +pthread_attr_setaffinity_np - Set Thread Affinity Attribute +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code:: c + + #define _GNU_SOURCE + #include + int pthread_attr_setaffinity_np( + pthread_attr_t \*attr, + size_t cpusetsize, + const cpu_set_t \*cpuset + ); + +**STATUS CODES:** + +*EFAULT* + The attribute pointer argument is invalid. + +*EFAULT* + The cpuset pointer argument is invalid. + +*EINVAL* + The ``cpusetsize`` does not match the value of ``affinitysetsize`` + field in the thread attribute object. + +*EINVAL* + The ``cpuset`` did not select a valid cpu. + +*EINVAL* + The ``cpuset`` selected a cpu that was invalid. + +**DESCRIPTION:** + +The ``pthread_attr_setaffinity_np`` routine is used to set the``affinityset`` field in the thread attribute object ``attr``. +The value of this field is returned in ``cpuset``. + +**NOTES:** + +NONE + +pthread_create - Create a Thread +-------------------------------- +.. index:: pthread_create +.. index:: create a thread + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_create`` routine is used to create a new thread with +the attributes specified by ``attr``. If the ``attr`` argument +is ``NULL``, then the default attribute set will be used. Modification +of the contents of ``attr`` after this thread is created does not +have an impact on this thread. + +The thread begins execution at the address specified by ``start_routine`` +with ``arg`` as its only argument. If ``start_routine`` returns, +then it is functionally equivalent to the thread executing the``pthread_exit`` service. + +Upon successful completion, the ID of the created thread is returned in the``thread`` argument. + +**NOTES:** + +There is no concept of a single main thread in RTEMS as there is in +a tradition UNIX system. POSIX requires that the implicit return of +the main thread results in the same effects as if there were a call +to ``exit``. This does not occur in RTEMS. + +The signal mask of the newly created thread is inherited from its +creator and the set of pending signals for this thread is empty. + +pthread_exit - Terminate the Current Thread +------------------------------------------- +.. index:: pthread_exit +.. index:: terminate the current thread + +**CALLING SEQUENCE:** + +.. code:: c + + #include + void pthread_exit( + void \*status + ); + +**STATUS CODES:** + +*NONE* + +**DESCRIPTION:** + +The ``pthread_exit`` routine is used to terminate the calling thread. +The ``status`` is made available to any successful join with the +terminating thread. + +When a thread returns from its start routine, it results in an +implicit call to the ``pthread_exit`` routine with the return +value of the function serving as the argument to ``pthread_exit``. + +**NOTES:** + +Any cancellation cleanup handlers that hace been pushed and not yet popped +shall be popped in reverse of the order that they were pushed. After +all cancellation cleanup handlers have been executed, if the +thread has any thread-specific data, destructors for that data will +be invoked. + +Thread termination does not release or free any application visible +resources including byt not limited to mutexes, file descriptors, allocated +memory, etc.. Similarly, exitting a thread does not result in any +process-oriented cleanup activity. + +There is no concept of a single main thread in RTEMS as there is in +a tradition UNIX system. POSIX requires that the implicit return of +the main thread results in the same effects as if there were a call +to ``exit``. This does not occur in RTEMS. + +All access to any automatic variables allocated by the threads is lost +when the thread exits. Thus references (i.e. pointers) to local variables +of a thread should not be used in a global manner without care. As +a specific example, a pointer to a local variable should NOT be used +as the return value. + +pthread_detach - Detach a Thread +-------------------------------- +.. index:: pthread_detach +.. index:: detach a thread + +**CALLING SEQUENCE:** + +.. code:: c + + #include + int pthread_detach( + pthread_t thread + ); + +**STATUS CODES:** + +*ESRCH* + The thread specified is invalid. + +*EINVAL* + The thread specified is not a joinable thread. + +**DESCRIPTION:** + +The ``pthread_detach`` routine is used to to indicate that storage +for ``thread`` can be reclaimed when the thread terminates without +another thread joinging with it. + +**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. + +.. COMMENT: pthread_getattr_np + +pthread_getattr_np - Get Thread Attributes +------------------------------------------ +.. index:: pthread_getattr_np +.. index:: get thread attributes + +**CALLING SEQUENCE:** + +.. code:: c + + #define _GNU_SOURCE + #include + int pthread_getattr_np( + pthread_t thread, + pthread_attr_t \*attr + ); + +**STATUS CODES:** + +*ESRCH* + The thread specified is invalid. + +*EINVAL* + The attribute pointer argument is invalid. + +**DESCRIPTION:** + +The ``pthread_getattr_np`` routine is used to obtain the +attributes associated with ``thread``. + +**NOTES:** + +Modification of the execution modes and priority through the Classic API +may result in a combination that is not representable in the POSIX API. + +pthread_join - Wait for Thread Termination +------------------------------------------ +.. index:: pthread_join +.. index:: wait for thread termination + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_join`` routine suspends execution of the calling thread +until ``thread`` terminates. If ``thread`` has already terminated, +then this routine returns immediately. The value returned by ``thread`` +(i.e. passed to ``pthread_exit`` is returned in ``value_ptr``. + +When this routine returns, then ``thread`` has been terminated. + +**NOTES:** + +The results of multiple simultaneous joins on the same thread is undefined. + +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 - Get Thread ID +---------------------------- +.. index:: pthread_self +.. index:: get thread id + +**CALLING SEQUENCE:** + +.. code:: c + + #include + pthread_t pthread_self( void ); + +**STATUS CODES:** + +The value returned is the ID of the calling thread. + +**DESCRIPTION:** + +This routine returns the ID of the calling thread. + +**NOTES:** + +NONE + +pthread_equal - Compare Thread IDs +---------------------------------- +.. index:: pthread_equal +.. index:: compare thread ids + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_equal`` routine is used to compare two thread +IDs and determine if they are equal. + +**NOTES:** + +The behavior is undefined if the thread IDs are not valid. + +pthread_once - Dynamic Package Initialization +--------------------------------------------- +.. index:: pthread_once +.. index:: dynamic package initialization + +**CALLING SEQUENCE:** + +.. code:: c + + #include + pthread_once_t once_control = PTHREAD_ONCE_INIT; + int pthread_once( + pthread_once_t \*once_control, + void (\*init_routine)(void) + ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +The ``pthread_once`` routine is used to provide controlled initialization +of variables. The first call to ``pthread_once`` by any thread with the +same ``once_control`` will result in the ``init_routine`` being +invoked with no arguments. Subsequent calls to ``pthread_once`` with +the same ``once_control`` will have no effect. + +The ``init_routine`` is guaranteed to have run to completion when +this routine returns to the caller. + +**NOTES:** + +The behavior of ``pthread_once`` is undefined if ``once_control`` +is automatic storage (i.e. on a task stack) or is not initialized using``PTHREAD_ONCE_INIT``. + +pthread_setschedparam - Set Thread Scheduling Parameters +-------------------------------------------------------- +.. index:: pthread_setschedparam +.. index:: set thread scheduling parameters + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_setschedparam`` routine is used to set the +scheduler parameters currently associated with the thread specified +by ``thread`` to the policy specified by ``policy``. The +contents of ``param`` are interpreted based upon the ``policy`` +argument. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +pthread_getschedparam - Get Thread Scheduling Parameters +-------------------------------------------------------- +.. index:: pthread_getschedparam +.. index:: get thread scheduling parameters + +**CALLING SEQUENCE:** + +.. code:: c + + #include + 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:** + +The ``pthread_getschedparam`` routine is used to obtain the +scheduler policy and parameters associated with ``thread``. +The current policy and associated parameters values returned in``policy`` and ``param``, respectively. + +**NOTES:** + +As required by POSIX, RTEMS defines the feature symbol``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the +family of routines to which this routine belongs is supported. + +.. COMMENT: pthread_getaffinity_np + +pthread_getaffinity_np - Get Thread Affinity +-------------------------------------------- + +**CALLING SEQUENCE:** + +.. code:: c + + #define _GNU_SOURCE + #include + int pthread_getaffinity_np( + const pthread_t id, + size_t cpusetsize, + cpu_set_t \*cpuset + ); + +**STATUS CODES:** + +*EFAULT* + The cpuset pointer argument is invalid. + +*EINVAL* + The ``cpusetsize`` does not match the value of ``affinitysetsize`` + field in the thread attribute object. + +**DESCRIPTION:** + +The ``pthread_getaffinity_np`` routine is used to obtain the``affinity.set`` field from the thread control object associated +with the ``id``. The value of this field is returned in ``cpuset``. + +**NOTES:** + +NONE + +.. COMMENT: pthread_setaffinity_np + +pthread_setaffinity_np - Set Thread Affinity +-------------------------------------------- + +**CALLING SEQUENCE:** + +.. code:: c + + #define _GNU_SOURCE + #include + int pthread_setaffinity_np( + pthread_t id, + size_t cpusetsize, + const cpu_set_t \*cpuset + ); + +**STATUS CODES:** + +*EFAULT* + The cpuset pointer argument is invalid. + +*EINVAL* + The ``cpusetsize`` does not match the value of ``affinitysetsize`` + field in the thread attribute object. + +*EINVAL* + The ``cpuset`` did not select a valid cpu. + +*EINVAL* + The ``cpuset`` selected a cpu that was invalid. + +**DESCRIPTION:** + +The ``pthread_setaffinity_np`` routine is used to set the``affinityset`` field of the thread object ``id``. +The value of this field is returned in ``cpuset`` + +**NOTES:** + +NONE + +.. COMMENT: COPYRIGHT (c) 1988-2002. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3