.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_GETCONCURRENCY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_getconcurrency 
.SH NAME
pthread_getconcurrency, pthread_setconcurrency \- get and set the level
of concurrency
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_getconcurrency(void);
.br
int pthread_setconcurrency(int\fP \fInew_level\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
Unbound threads in a process may or may not be required to be simultaneously
active. By default, the threads implementation
ensures that a sufficient number of threads are active so that the
process can continue to make progress. While this conserves
system resources, it may not produce the most effective level of concurrency.
.LP
The \fIpthread_setconcurrency\fP() function allows an application
to inform the threads implementation of its desired
concurrency level, \fInew_level\fP. The actual level of concurrency
provided by the implementation as a result of this function
call is unspecified.
.LP
If \fInew_level\fP is zero, it causes the implementation to maintain
the concurrency level at its discretion as if
\fIpthread_setconcurrency\fP() had never been called.
.LP
The \fIpthread_getconcurrency\fP() function shall return the value
set by a previous call to the
\fIpthread_setconcurrency\fP() function. If the \fIpthread_setconcurrency\fP()
function was not previously called, this function
shall return zero to indicate that the implementation is maintaining
the concurrency level.
.LP
A call to \fIpthread_setconcurrency\fP() shall inform the implementation
of its desired concurrency level. The implementation
shall use this as a hint, not a requirement.
.LP
If an implementation does not support multiplexing of user threads
on top of several kernel-scheduled entities, the
\fIpthread_setconcurrency\fP() and \fIpthread_getconcurrency\fP()
functions are provided for source code compatibility but they
shall have no effect when called. To maintain the function semantics,
the \fInew_level\fP parameter is saved when
\fIpthread_setconcurrency\fP() is called so that a subsequent call
to \fIpthread_getconcurrency\fP() shall return the same
value.
.SH RETURN VALUE
.LP
If successful, the \fIpthread_setconcurrency\fP() function shall return
zero; otherwise, an error number shall be returned to
indicate the error.
.LP
The \fIpthread_getconcurrency\fP() function shall always return the
concurrency level set by a previous call to
\fIpthread_setconcurrency\fP(). If the \fIpthread_setconcurrency\fP()
function has never been called,
\fIpthread_getconcurrency\fP() shall return zero.
.SH ERRORS
.LP
The \fIpthread_setconcurrency\fP() function shall fail if:
.TP 7
.B EINVAL
The value specified by \fInew_level\fP is negative.
.TP 7
.B EAGAIN
The value specific by \fInew_level\fP would cause a system resource
to be exceeded.
.sp
.LP
These functions shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Use of these functions changes the state of the underlying concurrency
upon which the application depends. Library developers
are advised to not use the \fIpthread_getconcurrency\fP() and \fIpthread_setconcurrency\fP()
functions since their use may
conflict with an applications use of these functions.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .