diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2008-10-24 21:56:41 -0500 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2008-10-29 14:54:15 -0500 |
| commit | 7896a15506175ec08f85b1fa964eddef9e44d2ac (patch) | |
| tree | 492bcfb60297c8fbf72c2a747b8ce162254e9a87 | |
| parent | b290aa63eb68660d0f2a27f671c5d79218a94fa3 (diff) | |
| download | man-pages-7896a15506175ec08f85b1fa964eddef9e44d2ac.tar.gz | |
pthread_attr_init.3: New page for pthread_attr_init(3) and pthread_attr_destroy(3)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
| -rw-r--r-- | man3/pthread_attr_init.3 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/man3/pthread_attr_init.3 b/man3/pthread_attr_init.3 new file mode 100644 index 0000000000..8d21daf01d --- /dev/null +++ b/man3/pthread_attr_init.3 @@ -0,0 +1,308 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH PTHREAD_ATTR_INIT 3 2008-10-24 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_init, pthread_attr_destroy \- initialize and destroy +thread attributes object +.SH SYNOPSIS +.nf +.B #include <pthread.h> + +.BI "int pthread_attr_init(pthread_attr_t *" attr ); +.BI "int pthread_attr_destroy(pthread_attr_t *" attr ); +.sp +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_attr_init () +function initializes the thread attributes object pointed to by +.IR attr +with default attribute values. +After this call, individual attributes of the object can be set +using various related functions (listed under SEE ALSO), +and then the object can be used in one or more +.BR pthread_create (3) +calls that create threads. + +Calling +.BR pthread_attr_init () +on a thread attributes object that has already been initialized +results in undefined behavior. + +When a thread attributes object is no longer required, +it should be destroyed using the +.BR pthread_attr_destroy () +function. +Destroying a thread attributes object has no effect +on threads that were created using that object. + +Once a thread attributes object has been destroyed, +it can be reinitialized using +.BR pthread_attr_init (). +Any other use of a destroyed thread attributes object +has undefined results. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a non-zero error number. +.SH ERRORS +POSIX.1-2001 documents an +.B ENOMEM +error for +.BR pthread_attr_init (); +on Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +The +.I pthread_attr_t +type should be treated as opaque: +any access to the object other than via pthreads functions +is non-portable and produces undefined results. +.SH EXAMPLE +The program below optionally makes use of +.BR pthread_attr_init () +and various related functions to initialize a thread attributes +object that is used to create a single thread. +Once created, the thread uses the +.BR pthread_getattr_np () +function (a non-standard GNU extension) to retrieve the thread's +attributes, and then displays those attributes. + +If the program is run with no command-line argument, +then it passes NULL as the +.I attr +argument of +.BR pthread_create (3), +so that the thread is created with default attributes. +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: + +.in +4n +.nf +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +$ ulimit \-s # No stack imit ==> default stack size is 2MB +unlimited +$ ./a.out +Thread attributes: + Detach state = PTHREAD_CREATE_JOINABLE + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_INHERIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 4096 bytes + Stack address = 0x40196000 + Stack size = 0x201000 bytes +.fi +.in + +When we supply a stack size as a command-line argument, +the program initializes a thread attributes object, +sets various attributes in that object, +and passes a pointer to the object in the call to +.BR pthread_create (3). +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: + +.in +4n +.nf +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +$ ./a.out 0x3000000 +posix_memalign() allocated at 0x40197000 +Thread attributes: + Detach state = PTHREAD_CREATE_DETACHED + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_EXPLICIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 0 bytes + Stack address = 0x40197000 + Stack size = 0x3000000 bytes +.fi +.in + +Here is the program source: + +.nf +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <errno.h> + +#define errExitEN(en, msg) { errno = en; perror(msg); \\ + exit(EXIT_FAILURE); } + +static void +display_pthread_attr(pthread_attr_t *attr, char *prefix) +{ + int s, i; + size_t v; + void *stkaddr; + struct sched_param sp; + + s = pthread_attr_getdetachstate(attr, &i); + if (s != 0) + errExitEN(s, "pthread_attr_getdetachstate"); + printf("%sDetach state = %s\\n", prefix, + (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : + (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : + "???"); + + s = pthread_attr_getscope(attr, &i); + if (s != 0) + errExitEN(s, "pthread_attr_getscope"); + printf("%sScope = %s\\n", prefix, + (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : + (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : + "???"); + + s = pthread_attr_getinheritsched(attr, &i); + if (s != 0) + errExitEN(s, "pthread_attr_getinheritsched"); + printf("%sInherit scheduler = %s\\n", prefix, + (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : + (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : + "???"); + + s = pthread_attr_getschedpolicy(attr, &i); + if (s != 0) + errExitEN(s, "pthread_attr_getschedpolicy"); + printf("%sScheduling policy = %s\\n", prefix, + (i == SCHED_OTHER) ? "SCHED_OTHER" : + (i == SCHED_FIFO) ? "SCHED_FIFO" : + (i == SCHED_RR) ? "SCHED_RR" : + "???"); + + s = pthread_attr_getschedparam(attr, &sp); + if (s != 0) + errExitEN(s, "pthread_attr_getschedparam"); + printf("%sScheduling priority = %d\\n", prefix, sp.sched_priority); + + s = pthread_attr_getguardsize(attr, &v); + if (s != 0) + errExitEN(s, "pthread_attr_getguardsize"); + printf("%sGuard size = %d bytes\\n", prefix, v); + + s = pthread_attr_getstack(attr, &stkaddr, &v); + if (s != 0) + errExitEN(s, "pthread_attr_getstack"); + printf("%sStack address = %p\\n", prefix, stkaddr); + printf("%sStack size = 0x%x bytes\\n", prefix, v); +} + +static void * +thread_start(void *arg) +{ + int s; + pthread_attr_t gattr; + + /* pthread_getattr_np() is a non\-standard GNU extension that + retrieves the attributes of the thread specified in its + first argument */ + + s = pthread_getattr_np(pthread_self(), &gattr); + if (s != 0) + errExitEN(s, "pthread_getattr_np"); + + printf("Thread attributes:\\n"); + display_pthread_attr(&gattr, "\\t"); + + exit(EXIT_SUCCESS); /* Terminate all threads */ +} + +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp; /* NULL or &attr */ + int s; + + attrp = NULL; + + /* If a command\-line argument was supplied, use it to set the + stack\-size attribute and set a few other thread attributes, + and set attrp pointing to thread attributes object */ + + if (argc > 1) { + int stack_size; + void *sp; + + attrp = &attr; + + s = pthread_attr_init(&attr); + if (s != 0) + errExitEN(s, "pthread_attr_init"); + + s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); + if (s != 0) + errExitEN(s, "pthread_attr_setdetachstate"); + + s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); + if (s != 0) + errExitEN(s, "pthread_attr_setinheritsched"); + + stack_size = strtoul(argv[1], NULL, 0); + + s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); + if (s != 0) + errExitEN(s, "posix_memalign"); + + printf("posix_memalign() allocated at %p\\n", sp); + + s = pthread_attr_setstack(&attr, sp, stack_size); + if (s != 0) + errExitEN(s, "pthread_attr_setstack"); + } + + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + errExitEN(s, "pthread_create"); + + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + errExitEN(s, "pthread_attr_destroy"); + } + + pause(); /* Terminates when other thread calls exit() */ +} +.fi +.SH SEE ALSO +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setdetachstate (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthread_getattr_np (3), +.BR pthreads (7) |