[rtems commit] POSIX Users Guide: Add thread affinity services.
Joel Sherrill
joel at rtems.org
Tue Mar 11 23:59:21 UTC 2014
Module: rtems
Branch: master
Commit: 4013d25bc2d46b1f24ed045d20533503a297b251
Changeset: http://git.rtems.org/rtems/commit/?id=4013d25bc2d46b1f24ed045d20533503a297b251
Author: Joel Sherrill <joel.sherrill at oarcorp.com>
Date: Fri Mar 7 13:18:40 2014 -0600
POSIX Users Guide: Add thread affinity services.
---
doc/posix_users/thread.t | 252 +++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 250 insertions(+), 2 deletions(-)
diff --git a/doc/posix_users/thread.t b/doc/posix_users/thread.t
index ce868bf..c630e03 100644
--- a/doc/posix_users/thread.t
+++ b/doc/posix_users/thread.t
@@ -1,5 +1,5 @@
@c
- at c COPYRIGHT (c) 1988-2002.
+ at 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
+ at item @code{pthread_attr_getaffinity_np} - Get Thread Affinity Attribute
+ at 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
+ at 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
+ at item @code{pthread_getaffinity_np} - Get Thread Affinity
+ at item @code{pthread_setaffinity_np} - Set Thread Affinity
@end itemize
@section Background
@@ -873,6 +878,110 @@ family of routines to which this routine belongs is supported.
@c
@c
@page
+ at subsection pthread_attr_getaffinity_np - Get Thread Affinity Attribute
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#define _GNU_SOURCE
+#include <pthread.h>
+
+int pthread_attr_getaffinity_np(
+ const pthread_attr_t *attr,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item EFAULT
+The attribute pointer argument is invalid.
+
+ at item EFAULT
+The cpuset pointer argument is invalid.
+
+ at item EINVAL
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{pthread_attr_getaffinity_np} routine is used to obtain the
+ at code{affinityset} field from the thread attribute object @code{attr}.
+The value of this field is returned in @code{cpuset}.
+
+ at subheading NOTES:
+
+NONE
+
+ at c
+ at c
+ at c
+ at page
+ at subsection pthread_attr_setaffinity_np - Set Thread Affinity Attribute
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#define _GNU_SOURCE
+#include <pthread.h>
+
+int pthread_attr_setaffinity_np(
+ pthread_attr_t *attr,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item EFAULT
+The attribute pointer argument is invalid.
+
+ at item EFAULT
+The cpuset pointer argument is invalid.
+
+ at item EINVAL
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at item EINVAL
+The @code{cpuset} did not select a valid cpu.
+
+ at item EINVAL
+The @code{cpuset} selected a cpu that was invalid.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{pthread_attr_setaffinity_np} routine is used to set the
+ at code{affinityset} field in the thread attribute object @code{attr}.
+The value of this field is returned in @code{cpuset}.
+
+ at subheading NOTES:
+
+NONE
+
+ at c
+ at c
+ at c
+ at page
@subsection pthread_create - Create a Thread
@findex pthread_create
@@ -1060,6 +1169,47 @@ will remain joined with that thread. Any subsequent calls to
@code{pthread_join} on the specified thread will fail.
@c
+ at c pthread_getattr_np
+ at c
+ at page
+ at subsection pthread_getattr_np - Get Thread Attributes
+
+ at findex pthread_getattr_np
+ at cindex get thread attributes
+
+ at subheading CALLING SEQUENCE:
+
+ at example
+#define _GNU_SOURCE
+#include <pthread.h>
+
+int pthread_getattr_np(
+ pthread_t thread,
+ pthread_attr_t *attr
+);
+ at end example
+
+ at subheading STATUS CODES:
+ at table @b
+ at item ESRCH
+The thread specified is invalid.
+
+ at item EINVAL
+The attribute pointer argument is invalid.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{pthread_getattr_np} routine is used to obtain the
+attributes associated with @code{thread}.
+
+ at 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.
+
+ at c
@c
@c
@page
@@ -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.
+
+ at c
+ at c pthread_getaffinity_np
+ at c
+ at page
+ at subsection pthread_getaffinity_np - Get Thread Affinity
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#define _GNU_SOURCE
+#include <pthread.h>
+
+int pthread_getaffinity_np(
+ const pthread_t id,
+ size_t cpusetsize,
+ cpu_set_t *cpuset
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item EFAULT
+The cpuset pointer argument is invalid.
+
+ at item EINVAL
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{pthread_getaffinity_np} routine is used to obtain the
+ at code{affinity.set} field from the thread control object associated
+with the @code{id}. The value of this field is returned in @code{cpuset}.
+
+ at subheading NOTES:
+
+NONE
+
+ at c
+ at c pthread_setaffinity_np
+ at c
+ at page
+ at subsection pthread_setaffinity_np - Set Thread Affinity
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+#define _GNU_SOURCE
+#include <pthread.h>
+
+int pthread_setaffinity_np(
+ pthread_t id,
+ size_t cpusetsize,
+ const cpu_set_t *cpuset
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+ at table @b
+ at item EFAULT
+The cpuset pointer argument is invalid.
+
+ at item EINVAL
+The @code{cpusetsize} does not match the value of @code{affinitysetsize}
+field in the thread attribute object.
+
+ at item EINVAL
+The @code{cpuset} did not select a valid cpu.
+
+ at item EINVAL
+The @code{cpuset} selected a cpu that was invalid.
+
+ at end table
+
+ at subheading DESCRIPTION:
+
+The @code{pthread_setaffinity_np} routine is used to set the
+ at code{affinityset} field of the thread object @code{id}.
+The value of this field is returned in @code{cpuset}
+
+ at subheading NOTES:
+
+NONE
More information about the vc
mailing list