source: rtems-docs/posix-users/thread.rst @ 3a58bff

4.115
Last change on this file since 3a58bff was 72a62ad, checked in by Chris Johns <chrisj@…>, on 11/03/16 at 05:58:08

Rename all manuals with an _ to have a -. It helps released naming of files.

  • Property mode set to 100644
File size: 36.1 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2002.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7Thread Manager
8##############
9
10Introduction
11============
12
13The thread manager implements the functionality required of the thread manager
14as defined by POSIX 1003.1b. This standard requires that a compliant operating
15system provide the facilties to manage multiple threads of control and defines
16the API that must be provided.
17
18The services provided by the thread manager are:
19
20- pthread_attr_init_ - Initialize a Thread Attribute Set
21
22- pthread_attr_destroy_ - Destroy a Thread Attribute Set
23
24- pthread_attr_setdetachstate_ - Set Detach State
25
26- pthread_attr_getdetachstate_ - Get Detach State
27
28- pthread_attr_setstacksize_ - Set Thread Stack Size
29
30- pthread_attr_getstacksize_ - Get Thread Stack Size
31
32- pthread_attr_setstackaddr_ - Set Thread Stack Address
33
34- pthread_attr_getstackaddr_ - Get Thread Stack Address
35
36- pthread_attr_setscope_ - Set Thread Scheduling Scope
37
38- pthread_attr_getscope_ - Get Thread Scheduling Scope
39
40- pthread_attr_setinheritsched_ - Set Inherit Scheduler Flag
41
42- pthread_attr_getinheritsched_ - Get Inherit Scheduler Flag
43
44- pthread_attr_setschedpolicy_ - Set Scheduling Policy
45
46- pthread_attr_getschedpolicy_ - Get Scheduling Policy
47
48- pthread_attr_setschedparam_ - Set Scheduling Parameters
49
50- pthread_attr_getschedparam_ - Get Scheduling Parameters
51
52- pthread_attr_getaffinity_np_ - Get Thread Affinity Attribute
53
54- pthread_attr_setaffinity_np_ - Set Thread Affinity Attribute
55
56- pthread_create_ - Create a Thread
57
58- pthread_exit_ - Terminate the Current Thread
59
60- pthread_detach_ - Detach a Thread
61
62- pthread_getattr_np_ - Get Thread Attributes
63
64- pthread_join_ - Wait for Thread Termination
65
66- pthread_self_ - Get Thread ID
67
68- pthread_equal_ - Compare Thread IDs
69
70- pthread_once_ - Dynamic Package Initialization
71
72- pthread_setschedparam_ - Set Thread Scheduling Parameters
73
74- pthread_getschedparam_ - Get Thread Scheduling Parameters
75
76- pthread_getaffinity_np_ - Get Thread Affinity
77
78- pthread_setaffinity_np_ - Set Thread Affinity
79
80Background
81==========
82
83Thread Attributes
84-----------------
85
86Thread attributes are utilized only at thread creation time. A thread attribute
87structure may be initialized and passed as an argument to the
88``pthread_create`` routine.
89
90*stack address*
91    is the address of the optionally user specified stack area for this thread.
92    If this value is NULL, then RTEMS allocates the memory for the thread stack
93    from the RTEMS Workspace Area. Otherwise, this is the user specified
94    address for the memory to be used for the thread's stack. Each thread must
95    have a distinct stack area. Each processor family has different alignment
96    rules which should be followed.
97
98*stack size*
99    is the minimum desired size for this thread's stack area.  If the size of
100    this area as specified by the stack size attribute is smaller than the
101    minimum for this processor family and the stack is not user specified, then
102    RTEMS will automatically allocate a stack of the minimum size for this
103    processor family.
104
105*contention scope*
106    specifies the scheduling contention scope. RTEMS only supports the
107    PTHREAD_SCOPE_PROCESS scheduling contention scope.
108
109*scheduling inheritance*
110    specifies whether a user specified or the scheduling policy and parameters
111    of the currently executing thread are to be used. When this is
112    PTHREAD_INHERIT_SCHED, then the scheduling policy and parameters of the
113    currently executing thread are inherited by the newly created thread.
114
115*scheduling policy and parameters*
116    specify the manner in which the thread will contend for the processor.  The
117    scheduling parameters are interpreted based on the specified policy.  All
118    policies utilize the thread priority parameter.
119
120Operations
121==========
122
123There is currently no text in this section.
124
125Services
126========
127
128This section details the thread manager's services.  A subsection is dedicated
129to each of this manager's services and describes the calling sequence, related
130constants, usage, and status codes.
131
132.. _pthread_attr_init:
133
134pthread_attr_init - Initialize a Thread Attribute Set
135-----------------------------------------------------
136.. index:: pthread_attr_init
137.. index:: initialize a thread attribute set
138
139**CALLING SEQUENCE:**
140
141.. code-block:: c
142
143    #include <pthread.h>
144    int pthread_attr_init(
145        pthread_attr_t *attr
146    );
147
148**STATUS CODES:**
149
150.. list-table::
151 :class: rtems-table
152
153 * - ``EINVAL``
154   - The attribute pointer argument is invalid.
155
156**DESCRIPTION:**
157
158The ``pthread_attr_init`` routine initializes the thread attributes object
159specified by ``attr`` with the default value for all of the individual
160attributes.
161
162**NOTES:**
163
164The settings in the default attributes are implementation defined. For RTEMS,
165the default attributes are as follows:
166
167.. list-table::
168 :class: rtems-table
169
170 * - *stackadr*
171   - is not set to indicate that RTEMS is to allocate the stack memory.
172 * - *stacksize*
173   - is set to ``PTHREAD_MINIMUM_STACK_SIZE``.
174 * - *contentionscope*
175   - is set to ``PTHREAD_SCOPE_PROCESS``.
176 * - *inheritsched*
177   - is set to ``PTHREAD_INHERIT_SCHED`` to indicate that the created thread
178     inherits its scheduling attributes from its parent.
179 * - detachstate
180   - is set to ``PTHREAD_CREATE_JOINABLE``.
181
182.. _pthread_attr_destroy:
183
184pthread_attr_destroy - Destroy a Thread Attribute Set
185-----------------------------------------------------
186.. index:: pthread_attr_destroy
187.. index:: destroy a thread attribute set
188
189**CALLING SEQUENCE:**
190
191.. code-block:: c
192
193    #include <pthread.h>
194    int pthread_attr_destroy(
195        pthread_attr_t *attr
196    );
197
198**STATUS CODES:**
199
200.. list-table::
201 :class: rtems-table
202
203 * - ``EINVAL``
204   - The attribute pointer argument is invalid.
205 * - ``EINVAL``
206   - The attribute set is not initialized.
207
208**DESCRIPTION:**
209
210The ``pthread_attr_destroy`` routine is used to destroy a thread attributes
211object. The behavior of using an attributes object after it is destroyed is
212implementation dependent.
213
214**NOTES:**
215
216NONE
217
218.. _pthread_attr_setdetachstate:
219
220pthread_attr_setdetachstate - Set Detach State
221----------------------------------------------
222.. index:: pthread_attr_setdetachstate
223.. index:: set detach state
224
225**CALLING SEQUENCE:**
226
227.. code-block:: c
228
229    #include <pthread.h>
230    int pthread_attr_setdetachstate(
231        pthread_attr_t *attr,
232        int             detachstate
233    );
234
235**STATUS CODES:**
236
237.. list-table::
238 :class: rtems-table
239
240 * - ``EINVAL``
241   - The attribute pointer argument is invalid.
242 * - ``EINVAL``
243   - The attribute set is not initialized.
244 * - ``EINVAL``
245   - The detachstate argument is invalid.
246
247**DESCRIPTION:**
248
249The ``pthread_attr_setdetachstate`` routine is used to value of the
250``detachstate`` attribute. This attribute controls whether the thread is
251created in a detached state.
252
253The ``detachstate`` can be either ``PTHREAD_CREATE_DETACHED`` or
254``PTHREAD_CREATE_JOINABLE``. The default value for all threads is
255``PTHREAD_CREATE_JOINABLE``.
256
257**NOTES:**
258
259If a thread is in a detached state, then the use of the ID with the
260``pthread_detach`` or ``pthread_join`` routines is an error.
261
262.. _pthread_attr_getdetachstate:
263
264pthread_attr_getdetachstate - Get Detach State
265----------------------------------------------
266.. index:: pthread_attr_getdetachstate
267.. index:: get detach state
268
269**CALLING SEQUENCE:**
270
271.. code-block:: c
272
273    #include <pthread.h>
274    int pthread_attr_getdetachstate(
275        const pthread_attr_t *attr,
276        int                  *detachstate
277    );
278
279**STATUS CODES:**
280
281.. list-table::
282 :class: rtems-table
283
284 * - ``EINVAL``
285   - The attribute pointer argument is invalid.
286 * - ``EINVAL``
287   - The attribute set is not initialized.
288 * - ``EINVAL``
289   - The detatchstate pointer argument is invalid.
290
291**DESCRIPTION:**
292
293The ``pthread_attr_getdetachstate`` routine is used to obtain the current value
294of the ``detachstate`` attribute as specified by the ``attr`` thread attribute
295object.
296
297**NOTES:**
298
299NONE
300
301.. _pthread_attr_setstacksize:
302
303pthread_attr_setstacksize - Set Thread Stack Size
304-------------------------------------------------
305.. index:: pthread_attr_setstacksize
306.. index:: set thread stack size
307
308**CALLING SEQUENCE:**
309
310.. code-block:: c
311
312    #include <pthread.h>
313    int pthread_attr_setstacksize(
314        pthread_attr_t *attr,
315        size_t          stacksize
316    );
317
318**STATUS CODES:**
319
320.. list-table::
321 :class: rtems-table
322
323 * - ``EINVAL``
324   - The attribute pointer argument is invalid.
325 * - ``EINVAL``
326   - The attribute set is not initialized.
327
328**DESCRIPTION:**
329
330The ``pthread_attr_setstacksize`` routine is used to set the ``stacksize``
331attribute in the ``attr`` thread attribute object.
332
333**NOTES:**
334
335As required by POSIX, RTEMS defines the feature symbol
336``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
337
338If the specified stacksize is below the minimum required for this CPU
339(``PTHREAD_STACK_MIN``, then the stacksize will be set to the minimum for this
340CPU.
341
342.. _pthread_attr_getstacksize:
343
344pthread_attr_getstacksize - Get Thread Stack Size
345-------------------------------------------------
346.. index:: pthread_attr_getstacksize
347.. index:: get thread stack size
348
349**CALLING SEQUENCE:**
350
351.. code-block:: c
352
353    #include <pthread.h>
354    int pthread_attr_getstacksize(
355        const pthread_attr_t *attr,
356        size_t               *stacksize
357    );
358
359**STATUS CODES:**
360
361.. list-table::
362 :class: rtems-table
363
364 * - ``EINVAL``
365   - The attribute pointer argument is invalid.
366 * - ``EINVAL``
367   - The attribute set is not initialized.
368 * - ``EINVAL``
369   - The stacksize pointer argument is invalid.
370
371**DESCRIPTION:**
372
373The ``pthread_attr_getstacksize`` routine is used to obtain the ``stacksize``
374attribute in the ``attr`` thread attribute object.
375
376**NOTES:**
377
378As required by POSIX, RTEMS defines the feature symbol
379``_POSIX_THREAD_ATTR_STACKSIZE`` to indicate that this routine is supported.
380
381.. _pthread_attr_setstackaddr:
382
383pthread_attr_setstackaddr - Set Thread Stack Address
384----------------------------------------------------
385.. index:: pthread_attr_setstackaddr
386.. index:: set thread stack address
387
388**CALLING SEQUENCE:**
389
390.. code-block:: c
391
392    #include <pthread.h>
393    int pthread_attr_setstackaddr(
394        pthread_attr_t *attr,
395        void           *stackaddr
396    );
397
398**STATUS CODES:**
399
400.. list-table::
401 :class: rtems-table
402
403 * - ``EINVAL``
404   - The attribute pointer argument is invalid.
405 * - ``EINVAL``
406   - The attribute set is not initialized.
407
408**DESCRIPTION:**
409
410The ``pthread_attr_setstackaddr`` routine is used to set the ``stackaddr``
411attribute in the ``attr`` thread attribute object.
412
413**NOTES:**
414
415As required by POSIX, RTEMS defines the feature symbol
416``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
417
418It is imperative to the proper operation of the system that each thread have
419sufficient stack space.
420
421.. _pthread_attr_getstackaddr:
422
423pthread_attr_getstackaddr - Get Thread Stack Address
424----------------------------------------------------
425.. index:: pthread_attr_getstackaddr
426.. index:: get thread stack address
427
428**CALLING SEQUENCE:**
429
430.. code-block:: c
431
432    #include <pthread.h>
433    int pthread_attr_getstackaddr(
434        const pthread_attr_t  *attr,
435        void                 **stackaddr
436    );
437
438**STATUS CODES:**
439
440.. list-table::
441 :class: rtems-table
442
443 * - ``EINVAL``
444   - The attribute pointer argument is invalid.
445 * - ``EINVAL``
446   - The attribute set is not initialized.
447 * - ``EINVAL``
448   - The stackaddr pointer argument is invalid.
449
450**DESCRIPTION:**
451
452The ``pthread_attr_getstackaddr`` routine is used to obtain the ``stackaddr``
453attribute in the ``attr`` thread attribute object.
454
455**NOTES:**
456
457As required by POSIX, RTEMS defines the feature symbol
458``_POSIX_THREAD_ATTR_STACKADDR`` to indicate that this routine is supported.
459
460.. _pthread_attr_setscope:
461
462pthread_attr_setscope - Set Thread Scheduling Scope
463---------------------------------------------------
464.. index:: pthread_attr_setscope
465.. index:: set thread scheduling scope
466
467**CALLING SEQUENCE:**
468
469.. code-block:: c
470
471    #include <pthread.h>
472    int pthread_attr_setscope(
473        pthread_attr_t *attr,
474        int             contentionscope
475    );
476
477**STATUS CODES:**
478
479.. list-table::
480 :class: rtems-table
481
482 * - ``EINVAL``
483   - The attribute pointer argument is invalid.
484 * - ``EINVAL``
485   - The attribute set is not initialized.
486 * - ``EINVAL``
487   - The contention scope specified is not valid.
488 * - ``ENOTSUP``
489   - The contention scope specified (``PTHREAD_SCOPE_SYSTEM``) is not supported.
490
491**DESCRIPTION:**
492
493The ``pthread_attr_setscope`` routine is used to set the contention scope field
494in the thread attribute object ``attr`` to the value specified by
495``contentionscope``.
496
497The ``contentionscope`` must be either ``PTHREAD_SCOPE_SYSTEM`` to indicate
498that the thread is to be within system scheduling contention or
499``PTHREAD_SCOPE_PROCESS`` indicating that the thread is to be within the
500process scheduling contention scope.
501
502**NOTES:**
503
504As required by POSIX, RTEMS defines the feature symbol
505``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
506to which this routine belongs is supported.
507
508.. _pthread_attr_getscope:
509
510pthread_attr_getscope - Get Thread Scheduling Scope
511---------------------------------------------------
512.. index:: pthread_attr_getscope
513.. index:: get thread scheduling scope
514
515**CALLING SEQUENCE:**
516
517.. code-block:: c
518
519    #include <pthread.h>
520    int pthread_attr_getscope(
521        const pthread_attr_t *attr,
522        int                  *contentionscope
523    );
524
525**STATUS CODES:**
526
527.. list-table::
528 :class: rtems-table
529
530 * - ``EINVAL``
531   - The attribute pointer argument is invalid.
532 * - ``EINVAL``
533   - The attribute set is not initialized.
534 * - ``EINVAL``
535   - The contentionscope pointer argument is invalid.
536
537**DESCRIPTION:**
538
539The ``pthread_attr_getscope`` routine is used to obtain the value of the
540contention scope field in the thread attributes object ``attr``. The current
541value is returned in ``contentionscope``.
542
543**NOTES:**
544
545As required by POSIX, RTEMS defines the feature symbol
546``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
547to which this routine belongs is supported.
548
549.. _pthread_attr_setinheritsched:
550
551pthread_attr_setinheritsched - Set Inherit Scheduler Flag
552---------------------------------------------------------
553.. index:: pthread_attr_setinheritsched
554.. index:: set inherit scheduler flag
555
556**CALLING SEQUENCE:**
557
558.. code-block:: c
559
560    #include <pthread.h>
561    int pthread_attr_setinheritsched(
562        pthread_attr_t *attr,
563        int             inheritsched
564    );
565
566**STATUS CODES:**
567
568.. list-table::
569 :class: rtems-table
570
571 * - ``EINVAL``
572   - The attribute pointer argument is invalid.
573 * - ``EINVAL``
574   - The attribute set is not initialized.
575 * - ``EINVAL``
576   - The specified scheduler inheritance argument is invalid.
577
578**DESCRIPTION:**
579
580The ``pthread_attr_setinheritsched`` routine is used to set the inherit
581scheduler field in the thread attribute object ``attr`` to the value specified
582by ``inheritsched``.
583
584The ``contentionscope`` must be either ``PTHREAD_INHERIT_SCHED`` to indicate
585that the thread is to inherit the scheduling policy and parameters fromthe
586creating thread, or ``PTHREAD_EXPLICIT_SCHED`` to indicate that the scheduling
587policy and parameters for this thread are to be set from the corresponding
588values in the attributes object.  If ``contentionscope`` is
589``PTHREAD_INHERIT_SCHED``, then the scheduling attributes in the ``attr``
590structure will be ignored at thread creation time.
591
592**NOTES:**
593
594As required by POSIX, RTEMS defines the feature symbol
595``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
596to which this routine belongs is supported.
597
598.. _pthread_attr_getinheritsched:
599
600pthread_attr_getinheritsched - Get Inherit Scheduler Flag
601---------------------------------------------------------
602.. index:: pthread_attr_getinheritsched
603.. index:: get inherit scheduler flag
604
605**CALLING SEQUENCE:**
606
607.. code-block:: c
608
609    #include <pthread.h>
610    int pthread_attr_getinheritsched(
611        const pthread_attr_t *attr,
612        int                  *inheritsched
613    );
614
615**STATUS CODES:**
616
617.. list-table::
618 :class: rtems-table
619
620 * - ``EINVAL``
621   - The attribute pointer argument is invalid.
622 * - ``EINVAL``
623   - The attribute set is not initialized.
624 * - ``EINVAL``
625   - The inheritsched pointer argument is invalid.
626
627**DESCRIPTION:**
628
629The ``pthread_attr_getinheritsched`` routine is used to object the current
630value of the inherit scheduler field in the thread attribute object ``attr``.
631
632**NOTES:**
633
634As required by POSIX, RTEMS defines the feature symbol
635``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
636to which this routine belongs is supported.
637
638.. _pthread_attr_setschedpolicy:
639
640pthread_attr_setschedpolicy - Set Scheduling Policy
641---------------------------------------------------
642.. index:: pthread_attr_setschedpolicy
643.. index:: set scheduling policy
644
645**CALLING SEQUENCE:**
646
647.. code-block:: c
648
649    #include <pthread.h>
650    int pthread_attr_setschedpolicy(
651        pthread_attr_t *attr,
652        int             policy
653    );
654
655**STATUS CODES:**
656
657.. list-table::
658 :class: rtems-table
659
660 * - ``EINVAL``
661   - The attribute pointer argument is invalid.
662 * - ``EINVAL``
663   - The attribute set is not initialized.
664 * - ``ENOTSUP``
665   - The specified scheduler policy argument is invalid.
666
667**DESCRIPTION:**
668
669The ``pthread_attr_setschedpolicy`` routine is used to set the scheduler policy
670field in the thread attribute object ``attr`` to the value specified by
671``policy``.
672
673Scheduling policies may be one of the following:
674
675- ``SCHED_DEFAULT``
676
677- ``SCHED_FIFO``
678
679- ``SCHED_RR``
680
681- ``SCHED_SPORADIC``
682
683- ``SCHED_OTHER``
684
685The precise meaning of each of these is discussed elsewhere in this manual.
686
687**NOTES:**
688
689As required by POSIX, RTEMS defines the feature symbol
690``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
691to which this routine belongs is supported.
692
693.. _pthread_attr_getschedpolicy:
694
695pthread_attr_getschedpolicy - Get Scheduling Policy
696---------------------------------------------------
697.. index:: pthread_attr_getschedpolicy
698.. index:: get scheduling policy
699
700**CALLING SEQUENCE:**
701
702.. code-block:: c
703
704    #include <pthread.h>
705    int pthread_attr_getschedpolicy(
706        const pthread_attr_t *attr,
707        int                  *policy
708    );
709
710**STATUS CODES:**
711
712.. list-table::
713 :class: rtems-table
714
715 * - ``EINVAL``
716   - The attribute pointer argument is invalid.
717 * - ``EINVAL``
718   - The attribute set is not initialized.
719 * - ``EINVAL``
720   - The specified scheduler policy argument pointer is invalid.
721
722**DESCRIPTION:**
723
724The ``pthread_attr_getschedpolicy`` routine is used to obtain the scheduler
725policy field from the thread attribute object ``attr``.  The value of this
726field is returned in ``policy``.
727
728**NOTES:**
729
730As required by POSIX, RTEMS defines the feature symbol
731``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
732to which this routine belongs is supported.
733
734.. _pthread_attr_setschedparam:
735
736pthread_attr_setschedparam - Set Scheduling Parameters
737------------------------------------------------------
738.. index:: pthread_attr_setschedparam
739.. index:: set scheduling parameters
740
741**CALLING SEQUENCE:**
742
743.. code-block:: c
744
745    #include <pthread.h>
746    int pthread_attr_setschedparam(
747        pthread_attr_t           *attr,
748        const struct sched_param  param
749    );
750
751**STATUS CODES:**
752
753.. list-table::
754 :class: rtems-table
755
756 * - ``EINVAL``
757   - The attribute pointer argument is invalid.
758 * - ``EINVAL``
759   - The attribute set is not initialized.
760 * - ``EINVAL``
761   - The specified scheduler parameter argument is invalid.
762
763**DESCRIPTION:**
764
765The ``pthread_attr_setschedparam`` routine is used to set the scheduler
766parameters field in the thread attribute object ``attr`` to the value specified
767by ``param``.
768
769**NOTES:**
770
771As required by POSIX, RTEMS defines the feature symbol
772``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
773to which this routine belongs is supported.
774
775.. _pthread_attr_getschedparam:
776
777pthread_attr_getschedparam - Get Scheduling Parameters
778------------------------------------------------------
779.. index:: pthread_attr_getschedparam
780.. index:: get scheduling parameters
781
782**CALLING SEQUENCE:**
783
784.. code-block:: c
785
786    #include <pthread.h>
787    int pthread_attr_getschedparam(
788        const pthread_attr_t *attr,
789        struct sched_param   *param
790    );
791
792**STATUS CODES:**
793
794.. list-table::
795 :class: rtems-table
796
797 * - ``EINVAL``
798   - The attribute pointer argument is invalid.
799 * - ``EINVAL``
800   - The attribute set is not initialized.
801 * - ``EINVAL``
802   - The specified scheduler parameter argument pointer is invalid.
803
804**DESCRIPTION:**
805
806The ``pthread_attr_getschedparam`` routine is used to obtain the scheduler
807parameters field from the thread attribute object ``attr``.  The value of this
808field is returned in ``param``.
809
810**NOTES:**
811
812As required by POSIX, RTEMS defines the feature symbol
813``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
814to which this routine belongs is supported.
815
816.. _pthread_attr_getaffinity_np:
817
818pthread_attr_getaffinity_np - Get Thread Affinity Attribute
819-----------------------------------------------------------
820
821**CALLING SEQUENCE:**
822
823.. code-block:: c
824
825    #define _GNU_SOURCE
826    #include <pthread.h>
827    int pthread_attr_getaffinity_np(
828        const pthread_attr_t *attr,
829        size_t                cpusetsize,
830        cpu_set_t            *cpuset
831    );
832
833**STATUS CODES:**
834
835.. list-table::
836 :class: rtems-table
837
838 * - ``EFAULT``
839   - The attribute pointer argument is invalid.
840 * - ``EFAULT``
841   - The cpuset pointer argument is invalid.
842 * - ``EINVAL``
843   - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
844     in the thread attribute object.
845
846**DESCRIPTION:**
847
848The ``pthread_attr_getaffinity_np`` routine is used to obtain the
849``affinityset`` field from the thread attribute object ``attr``.  The value of
850this field is returned in ``cpuset``.
851
852**NOTES:**
853
854NONE
855
856.. _pthread_attr_setaffinity_np:
857
858pthread_attr_setaffinity_np - Set Thread Affinity Attribute
859-----------------------------------------------------------
860
861**CALLING SEQUENCE:**
862
863.. code-block:: c
864
865    #define _GNU_SOURCE
866    #include <pthread.h>
867    int pthread_attr_setaffinity_np(
868        pthread_attr_t    *attr,
869        size_t             cpusetsize,
870        const cpu_set_t   *cpuset
871    );
872
873**STATUS CODES:**
874
875.. list-table::
876 :class: rtems-table
877
878 * - ``EFAULT``
879   - The attribute pointer argument is invalid.
880 * - ``EFAULT``
881   - The cpuset pointer argument is invalid.
882 * - ``EINVAL``
883   - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
884     in the thread attribute object.
885 * - ``EINVAL``
886   - The ``cpuset`` did not select a valid cpu.
887 * - ``EINVAL``
888   - The ``cpuset`` selected a cpu that was invalid.
889
890**DESCRIPTION:**
891
892The ``pthread_attr_setaffinity_np`` routine is used to set the ``affinityset``
893field in the thread attribute object ``attr``.  The value of this field is
894returned in ``cpuset``.
895
896**NOTES:**
897
898NONE
899
900.. _pthread_create:
901
902pthread_create - Create a Thread
903--------------------------------
904.. index:: pthread_create
905.. index:: create a thread
906
907**CALLING SEQUENCE:**
908
909.. code-block:: c
910
911    #include <pthread.h>
912    int pthread_create(
913        pthread_t             *thread,
914        const pthread_attr_t  *attr,
915        void                 (*start_routine)( void *),
916        void                  *arg
917    );
918
919**STATUS CODES:**
920
921.. list-table::
922 :class: rtems-table
923
924 * - ``EINVAL``
925   - The attribute set is not initialized.
926 * - ``EINVAL``
927   - The user specified a stack address and the size of the area was not large
928     enough to meet this processor's minimum stack requirements.
929 * - ``EINVAL``
930   - The specified scheduler inheritance policy was invalid.
931 * - ``ENOTSUP``
932   - The specified contention scope was ``PTHREAD_SCOPE_PROCESS``.
933 * - ``EINVAL``
934   - The specified thread priority was invalid.
935 * - ``EINVAL``
936   - The specified scheduling policy was invalid.
937 * - ``EINVAL``
938   - The scheduling policy was ``SCHED_SPORADIC`` and the specified
939     replenishment period is less than the initial budget.
940 * - ``EINVAL``
941   - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
942     priority is invalid.
943 * - ``EAGAIN``
944   - The system lacked the necessary resources to create another thread, or the
945     self imposed limit on the total number of threads in a process
946     ``PTHREAD_THREAD_MAX`` would be exceeded.
947 * - ``EINVAL``
948   - Invalid argument passed.
949
950**DESCRIPTION:**
951
952The ``pthread_create`` routine is used to create a new thread with the
953attributes specified by ``attr``. If the ``attr`` argument is ``NULL``, then
954the default attribute set will be used. Modification of the contents of
955``attr`` after this thread is created does not have an impact on this thread.
956
957The thread begins execution at the address specified by ``start_routine`` with
958``arg`` as its only argument. If ``start_routine`` returns, then it is
959functionally equivalent to the thread executing the ``pthread_exit`` service.
960
961Upon successful completion, the ID of the created thread is returned in the
962``thread`` argument.
963
964**NOTES:**
965
966There is no concept of a single main thread in RTEMS as there is in a tradition
967UNIX system. POSIX requires that the implicit return of the main thread results
968in the same effects as if there were a call to ``exit``. This does not occur in
969RTEMS.
970
971The signal mask of the newly created thread is inherited from its creator and
972the set of pending signals for this thread is empty.
973
974.. _pthread_exit:
975
976pthread_exit - Terminate the Current Thread
977-------------------------------------------
978.. index:: pthread_exit
979.. index:: terminate the current thread
980
981**CALLING SEQUENCE:**
982
983.. code-block:: c
984
985    #include <pthread.h>
986    void pthread_exit(
987        void *status
988    );
989
990**STATUS CODES:**
991
992*NONE*
993
994**DESCRIPTION:**
995
996The ``pthread_exit`` routine is used to terminate the calling thread.  The
997``status`` is made available to any successful join with the terminating
998thread.
999
1000When a thread returns from its start routine, it results in an implicit call to
1001the ``pthread_exit`` routine with the return value of the function serving as
1002the argument to ``pthread_exit``.
1003
1004**NOTES:**
1005
1006Any cancellation cleanup handlers that hace been pushed and not yet popped
1007shall be popped in reverse of the order that they were pushed. After all
1008cancellation cleanup handlers have been executed, if the thread has any
1009thread-specific data, destructors for that data will be invoked.
1010
1011Thread termination does not release or free any application visible resources
1012including byt not limited to mutexes, file descriptors, allocated memory,
1013etc.. Similarly, exitting a thread does not result in any process-oriented
1014cleanup activity.
1015
1016There is no concept of a single main thread in RTEMS as there is in a tradition
1017UNIX system. POSIX requires that the implicit return of the main thread results
1018in the same effects as if there were a call to ``exit``. This does not occur in
1019RTEMS.
1020
1021All access to any automatic variables allocated by the threads is lost when the
1022thread exits. Thus references (i.e. pointers) to local variables of a thread
1023should not be used in a global manner without care. As a specific example, a
1024pointer to a local variable should NOT be used as the return value.
1025
1026.. _pthread_detach:
1027
1028pthread_detach - Detach a Thread
1029--------------------------------
1030.. index:: pthread_detach
1031.. index:: detach a thread
1032
1033**CALLING SEQUENCE:**
1034
1035.. code-block:: c
1036
1037    #include <pthread.h>
1038    int pthread_detach(
1039        pthread_t thread
1040    );
1041
1042**STATUS CODES:**
1043
1044.. list-table::
1045 :class: rtems-table
1046
1047 * - ``ESRCH``
1048   - The thread specified is invalid.
1049 * - ``EINVAL``
1050   - The thread specified is not a joinable thread.
1051
1052**DESCRIPTION:**
1053
1054The ``pthread_detach`` routine is used to to indicate that storage for
1055``thread`` can be reclaimed when the thread terminates without another thread
1056joinging with it.
1057
1058**NOTES:**
1059
1060If any threads have previously joined with the specified thread, then they will
1061remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
1062specified thread will fail.
1063
1064.. COMMENT: pthread_getattr_np
1065
1066.. _pthread_getattr_np:
1067
1068pthread_getattr_np - Get Thread Attributes
1069------------------------------------------
1070.. index:: pthread_getattr_np
1071.. index:: get thread attributes
1072
1073**CALLING SEQUENCE:**
1074
1075.. code-block:: c
1076
1077    #define _GNU_SOURCE
1078    #include <pthread.h>
1079    int pthread_getattr_np(
1080        pthread_t       thread,
1081        pthread_attr_t *attr
1082    );
1083
1084**STATUS CODES:**
1085
1086.. list-table::
1087 :class: rtems-table
1088
1089 * - ``ESRCH``
1090   - The thread specified is invalid.
1091 * - ``EINVAL``
1092   - The attribute pointer argument is invalid.
1093
1094**DESCRIPTION:**
1095
1096The ``pthread_getattr_np`` routine is used to obtain the attributes associated
1097with ``thread``.
1098
1099**NOTES:**
1100
1101Modification of the execution modes and priority through the Classic API may
1102result in a combination that is not representable in the POSIX API.
1103
1104.. _pthread_join:
1105
1106pthread_join - Wait for Thread Termination
1107------------------------------------------
1108.. index:: pthread_join
1109.. index:: wait for thread termination
1110
1111**CALLING SEQUENCE:**
1112
1113.. code-block:: c
1114
1115    #include <pthread.h>
1116    int pthread_join(
1117        pthread_t    thread,
1118        void       **value_ptr
1119    );
1120
1121**STATUS CODES:**
1122
1123.. list-table::
1124 :class: rtems-table
1125
1126 * - ``ESRCH``
1127   - The thread specified is invalid.
1128 * - ``EINVAL``
1129   - The thread specified is not a joinable thread.
1130 * - ``EDEADLK``
1131   - A deadlock was detected or thread is the calling thread.
1132
1133**DESCRIPTION:**
1134
1135The ``pthread_join`` routine suspends execution of the calling thread until
1136``thread`` terminates. If ``thread`` has already terminated, then this routine
1137returns immediately. The value returned by ``thread`` (i.e. passed to
1138``pthread_exit`` is returned in ``value_ptr``.
1139
1140When this routine returns, then ``thread`` has been terminated.
1141
1142**NOTES:**
1143
1144The results of multiple simultaneous joins on the same thread is undefined.
1145
1146If any threads have previously joined with the specified thread, then they will
1147remain joined with that thread. Any subsequent calls to ``pthread_join`` on the
1148specified thread will fail.
1149
1150If value_ptr is NULL, then no value is returned.
1151
1152.. _pthread_self:
1153
1154pthread_self - Get Thread ID
1155----------------------------
1156.. index:: pthread_self
1157.. index:: get thread id
1158
1159**CALLING SEQUENCE:**
1160
1161.. code-block:: c
1162
1163    #include <pthread.h>
1164    pthread_t pthread_self( void );
1165
1166**STATUS CODES:**
1167
1168The value returned is the ID of the calling thread.
1169
1170**DESCRIPTION:**
1171
1172This routine returns the ID of the calling thread.
1173
1174**NOTES:**
1175
1176NONE
1177
1178.. _pthread_equal:
1179
1180pthread_equal - Compare Thread IDs
1181----------------------------------
1182.. index:: pthread_equal
1183.. index:: compare thread ids
1184
1185**CALLING SEQUENCE:**
1186
1187.. code-block:: c
1188
1189    #include <pthread.h>
1190    int pthread_equal(
1191        pthread_t t1,
1192        pthread_t t2
1193    );
1194
1195**STATUS CODES:**
1196
1197.. list-table::
1198 :class: rtems-table
1199
1200 * - ``zero``
1201   - The thread ids are not equal.
1202 * - ``non-zero``
1203   - The thread ids are equal.
1204
1205**DESCRIPTION:**
1206
1207The ``pthread_equal`` routine is used to compare two thread IDs and determine
1208if they are equal.
1209
1210**NOTES:**
1211
1212The behavior is undefined if the thread IDs are not valid.
1213
1214.. _pthread_once:
1215
1216pthread_once - Dynamic Package Initialization
1217---------------------------------------------
1218.. index:: pthread_once
1219.. index:: dynamic package initialization
1220
1221**CALLING SEQUENCE:**
1222
1223.. code-block:: c
1224
1225    #include <pthread.h>
1226    pthread_once_t once_control = PTHREAD_ONCE_INIT;
1227    int pthread_once(
1228        pthread_once_t   *once_control,
1229        void            (*init_routine)(void)
1230    );
1231
1232**STATUS CODES:**
1233
1234NONE
1235
1236**DESCRIPTION:**
1237
1238The ``pthread_once`` routine is used to provide controlled initialization of
1239variables. The first call to ``pthread_once`` by any thread with the same
1240``once_control`` will result in the ``init_routine`` being invoked with no
1241arguments. Subsequent calls to ``pthread_once`` with the same ``once_control``
1242will have no effect.
1243
1244The ``init_routine`` is guaranteed to have run to completion when this routine
1245returns to the caller.
1246
1247**NOTES:**
1248
1249The behavior of ``pthread_once`` is undefined if ``once_control`` is automatic
1250storage (i.e. on a task stack) or is not initialized using
1251``PTHREAD_ONCE_INIT``.
1252
1253.. _pthread_setschedparam:
1254
1255pthread_setschedparam - Set Thread Scheduling Parameters
1256--------------------------------------------------------
1257.. index:: pthread_setschedparam
1258.. index:: set thread scheduling parameters
1259
1260**CALLING SEQUENCE:**
1261
1262.. code-block:: c
1263
1264    #include <pthread.h>
1265    int pthread_setschedparam(
1266        pthread_t           thread,
1267        int                 policy,
1268        struct sched_param *param
1269    );
1270
1271**STATUS CODES:**
1272
1273.. list-table::
1274 :class: rtems-table
1275
1276 * - ``EINVAL``
1277   - The scheduling parameters indicated by the parameter param is invalid.
1278 * - ``EINVAL``
1279   - The value specified by policy is invalid.
1280 * - ``EINVAL``
1281   - The scheduling policy was ``SCHED_SPORADIC`` and the specified
1282     replenishment period is less than the initial budget.
1283 * - ``EINVAL``
1284   - The scheduling policy was ``SCHED_SPORADIC`` and the specified low
1285     priority is invalid.
1286 * - ``ESRCH``
1287   - The thread indicated was invalid.
1288
1289**DESCRIPTION:**
1290
1291The ``pthread_setschedparam`` routine is used to set the scheduler parameters
1292currently associated with the thread specified by ``thread`` to the policy
1293specified by ``policy``. The contents of ``param`` are interpreted based upon
1294the ``policy`` argument.
1295
1296**NOTES:**
1297
1298As required by POSIX, RTEMS defines the feature symbol
1299``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
1300to which this routine belongs is supported.
1301
1302.. _pthread_getschedparam:
1303
1304pthread_getschedparam - Get Thread Scheduling Parameters
1305--------------------------------------------------------
1306.. index:: pthread_getschedparam
1307.. index:: get thread scheduling parameters
1308
1309**CALLING SEQUENCE:**
1310
1311.. code-block:: c
1312
1313    #include <pthread.h>
1314    int pthread_getschedparam(
1315        pthread_t           thread,
1316        int                *policy,
1317        struct sched_param *param
1318    );
1319
1320**STATUS CODES:**
1321
1322.. list-table::
1323 :class: rtems-table
1324
1325 * - ``EINVAL``
1326   - The policy pointer argument is invalid.
1327 * - ``EINVAL``
1328   - The scheduling parameters pointer argument is invalid.
1329 * - ``ESRCH``
1330   - The thread indicated by the parameter thread is invalid.
1331
1332**DESCRIPTION:**
1333
1334The ``pthread_getschedparam`` routine is used to obtain the scheduler policy
1335and parameters associated with ``thread``.  The current policy and associated
1336parameters values returned in``policy`` and ``param``, respectively.
1337
1338**NOTES:**
1339
1340As required by POSIX, RTEMS defines the feature symbol
1341``_POSIX_THREAD_PRIORITY_SCHEDULING`` to indicate that the family of routines
1342to which this routine belongs is supported.
1343
1344.. COMMENT: pthread_getaffinity_np
1345
1346.. _pthread_getaffinity_np:
1347
1348pthread_getaffinity_np - Get Thread Affinity
1349--------------------------------------------
1350
1351**CALLING SEQUENCE:**
1352
1353.. code-block:: c
1354
1355    #define _GNU_SOURCE
1356    #include <pthread.h>
1357    int pthread_getaffinity_np(
1358        const pthread_t       id,
1359        size_t                cpusetsize,
1360        cpu_set_t            *cpuset
1361    );
1362
1363**STATUS CODES:**
1364
1365.. list-table::
1366 :class: rtems-table
1367
1368 * - ``EFAULT``
1369   - The cpuset pointer argument is invalid.
1370 * - ``EINVAL``
1371   - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
1372     in the thread attribute object.
1373
1374**DESCRIPTION:**
1375
1376The ``pthread_getaffinity_np`` routine is used to obtain the ``affinity.set``
1377field from the thread control object associated with the ``id``.  The value of
1378this field is returned in ``cpuset``.
1379
1380**NOTES:**
1381
1382NONE
1383
1384.. COMMENT: pthread_setaffinity_np
1385
1386.. _pthread_setaffinity_np:
1387
1388pthread_setaffinity_np - Set Thread Affinity
1389--------------------------------------------
1390
1391**CALLING SEQUENCE:**
1392
1393.. code-block:: c
1394
1395    #define _GNU_SOURCE
1396    #include <pthread.h>
1397    int pthread_setaffinity_np(
1398        pthread_t          id,
1399        size_t             cpusetsize,
1400        const cpu_set_t   *cpuset
1401    );
1402
1403**STATUS CODES:**
1404
1405.. list-table::
1406 :class: rtems-table
1407
1408 * - ``EFAULT``
1409   - The cpuset pointer argument is invalid.
1410 * - ``EINVAL``
1411   - The ``cpusetsize`` does not match the value of ``affinitysetsize`` field
1412     in the thread attribute object.
1413 * - ``EINVAL``
1414   - The ``cpuset`` did not select a valid cpu.
1415 * - ``EINVAL``
1416   - The ``cpuset`` selected a cpu that was invalid.
1417
1418**DESCRIPTION:**
1419
1420The ``pthread_setaffinity_np`` routine is used to set the ``affinityset`` field
1421of the thread object ``id``.  The value of this field is returned in ``cpuset``
1422
1423**NOTES:**
1424
1425NONE
Note: See TracBrowser for help on using the repository browser.