From 4013d25bc2d46b1f24ed045d20533503a297b251 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 7 Mar 2014 13:18:40 -0600 Subject: POSIX Users Guide: Add thread affinity services. --- doc/posix_users/thread.t | 252 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 250 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/posix_users/thread.t b/doc/posix_users/thread.t index ce868bf435..c630e03d6e 100644 --- a/doc/posix_users/thread.t +++ b/doc/posix_users/thread.t @@ -1,5 +1,5 @@ @c -@c COPYRIGHT (c) 1988-2002. +@c COPYRIGHT (c) 1988-2014. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @@ -8,7 +8,7 @@ @section Introduction The thread manager implements the functionality required of the thread -manager as defined by POSIX 1003.1b-1996. This standard requires that +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. @@ -31,15 +31,20 @@ The services provided by the thread manager are: @item @code{pthread_attr_getschedpolicy} - Get Scheduling Policy @item @code{pthread_attr_setschedparam} - Set Scheduling Parameters @item @code{pthread_attr_getschedparam} - Get Scheduling Parameters +@item @code{pthread_attr_getaffinity_np} - Get Thread Affinity Attribute +@item @code{pthread_attr_setaffinity_np} - Set Thread Affinity Attribute @item @code{pthread_create} - Create a Thread @item @code{pthread_exit} - Terminate the Current Thread @item @code{pthread_detach} - Detach a Thread +@item @code{pthread_getattr_np} - Get Thread Attributes @item @code{pthread_join} - Wait for Thread Termination @item @code{pthread_self} - Get Thread ID @item @code{pthread_equal} - Compare Thread IDs @item @code{pthread_once} - Dynamic Package Initialization @item @code{pthread_setschedparam} - Set Thread Scheduling Parameters @item @code{pthread_getschedparam} - Get Thread Scheduling Parameters +@item @code{pthread_getaffinity_np} - Get Thread Affinity +@item @code{pthread_setaffinity_np} - Set Thread Affinity @end itemize @section Background @@ -869,6 +874,110 @@ As required by POSIX, RTEMS defines the feature symbol @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the family of routines to which this routine belongs is supported. +@c +@c +@c +@page +@subsection pthread_attr_getaffinity_np - Get Thread Affinity Attribute + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#define _GNU_SOURCE +#include + +int pthread_attr_getaffinity_np( + const pthread_attr_t *attr, + size_t cpusetsize, + cpu_set_t *cpuset +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EFAULT +The attribute pointer argument is invalid. + +@item EFAULT +The cpuset pointer argument is invalid. + +@item EINVAL +The @code{cpusetsize} does not match the value of @code{affinitysetsize} +field in the thread attribute object. + +@end table + +@subheading DESCRIPTION: + +The @code{pthread_attr_getaffinity_np} routine is used to obtain the +@code{affinityset} field from the thread attribute object @code{attr}. +The value of this field is returned in @code{cpuset}. + +@subheading NOTES: + +NONE + +@c +@c +@c +@page +@subsection pthread_attr_setaffinity_np - Set Thread Affinity Attribute + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#define _GNU_SOURCE +#include + +int pthread_attr_setaffinity_np( + pthread_attr_t *attr, + size_t cpusetsize, + const cpu_set_t *cpuset +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EFAULT +The attribute pointer argument is invalid. + +@item EFAULT +The cpuset pointer argument is invalid. + +@item EINVAL +The @code{cpusetsize} does not match the value of @code{affinitysetsize} +field in the thread attribute object. + +@item EINVAL +The @code{cpuset} did not select a valid cpu. + +@item EINVAL +The @code{cpuset} selected a cpu that was invalid. + +@end table + +@subheading DESCRIPTION: + +The @code{pthread_attr_setaffinity_np} routine is used to set the +@code{affinityset} field in the thread attribute object @code{attr}. +The value of this field is returned in @code{cpuset}. + +@subheading NOTES: + +NONE + @c @c @c @@ -1059,6 +1168,47 @@ If any threads have previously joined with the specified thread, then they will remain joined with that thread. Any subsequent calls to @code{pthread_join} on the specified thread will fail. +@c +@c pthread_getattr_np +@c +@page +@subsection pthread_getattr_np - Get Thread Attributes + +@findex pthread_getattr_np +@cindex get thread attributes + +@subheading CALLING SEQUENCE: + +@example +#define _GNU_SOURCE +#include + +int pthread_getattr_np( + pthread_t thread, + pthread_attr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread specified is invalid. + +@item EINVAL +The attribute pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +The @code{pthread_getattr_np} routine is used to obtain the +attributes associated with @code{thread}. + +@subheading 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. + @c @c @c @@ -1327,3 +1477,101 @@ The current policy and associated parameters values returned in As required by POSIX, RTEMS defines the feature symbol @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the family of routines to which this routine belongs is supported. + +@c +@c pthread_getaffinity_np +@c +@page +@subsection pthread_getaffinity_np - Get Thread Affinity + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#define _GNU_SOURCE +#include + +int pthread_getaffinity_np( + const pthread_t id, + size_t cpusetsize, + cpu_set_t *cpuset +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EFAULT +The cpuset pointer argument is invalid. + +@item EINVAL +The @code{cpusetsize} does not match the value of @code{affinitysetsize} +field in the thread attribute object. + +@end table + +@subheading DESCRIPTION: + +The @code{pthread_getaffinity_np} routine is used to obtain the +@code{affinity.set} field from the thread control object associated +with the @code{id}. The value of this field is returned in @code{cpuset}. + +@subheading NOTES: + +NONE + +@c +@c pthread_setaffinity_np +@c +@page +@subsection pthread_setaffinity_np - Set Thread Affinity + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#define _GNU_SOURCE +#include + +int pthread_setaffinity_np( + pthread_t id, + size_t cpusetsize, + const cpu_set_t *cpuset +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EFAULT +The cpuset pointer argument is invalid. + +@item EINVAL +The @code{cpusetsize} does not match the value of @code{affinitysetsize} +field in the thread attribute object. + +@item EINVAL +The @code{cpuset} did not select a valid cpu. + +@item EINVAL +The @code{cpuset} selected a cpu that was invalid. + +@end table + +@subheading DESCRIPTION: + +The @code{pthread_setaffinity_np} routine is used to set the +@code{affinityset} field of the thread object @code{id}. +The value of this field is returned in @code{cpuset} + +@subheading NOTES: + +NONE -- cgit v1.2.3