1.\" $OpenBSD: pthread_getconcurrency.3,v 1.4 2013/06/05 03:44:50 tedu Exp $
2.\"
3.\" Copyright (c) 2003 Sergey Osokin <osa@FreeBSD.org.ru>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" $FreeBSD: src/lib/libc_r/man/pthread_getconcurrency.3,v 1.2 2003/05/24 19:50:43 ru Exp $
28.Dd $Mdocdate: June 5 2013 $
29.Dt PTHREAD_GETCONCURRENCY 3
30.Os
31.Sh NAME
32.Nm pthread_getconcurrency ,
33.Nm pthread_setconcurrency
34.Nd get or set level of concurrency
35.Sh SYNOPSIS
36.In pthread.h
37.Ft int
38.Fn pthread_getconcurrency void
39.Ft int
40.Fn pthread_setconcurrency "int new_level"
41.Sh DESCRIPTION
42The
43.Fn pthread_setconcurrency
44function allows an application to inform the threads implementation
45of its desired concurrency level,
46.Fa new_level .
47The actual level of concurrency provided by the implementation
48as a result of this function call is unspecified.
49If
50.Fa new_level
51is zero, it causes the implementation to maintain the concurrency
52level at its discretion as if
53.Fn pthread_setconcurrency
54was never called.
55The
56.Fn pthread_getconcurrency
57function returns the value set by a previous call to the
58.Fn pthread_setconcurrency
59function.
60If the
61.Fn pthread_setconcurrency
62function was not previously called, this function returns zero to
63indicate that the implementation is maintaining the concurrency
64level.
65When an application calls
66.Fn pthread_setconcurrency ,
67it is informing the implementation of its desired concurrency
68level.
69The implementation uses this as a hint, not a requirement.
70.Sh RETURN VALUES
71If successful, the
72.Fn pthread_setconcurrency
73function returns zero.
74Otherwise, an error number is returned
75to indicate the error.
76The
77.Fn pthread_getconcurrency
78function always returns the concurrency level set by a previous
79call to
80.Fn pthread_setconcurrency .
81If the
82.Fn pthread_setconcurrency
83function has never been called,
84.Fn pthread_getconcurrency
85returns zero.
86.Sh ERRORS
87.Fn pthread_setconcurrency
88will fail if:
89.Bl -tag -width Er
90.It Bq Er EINVAL
91The value specified by
92.Fa new_level
93is negative.
94.It Bq Er EAGAIN
95The value specified by
96.Fa new_level
97would cause a system resource to be exceeded.
98.El
99.Sh APPLICATION USAGE
100Use of these functions changes the state of the underlying
101concurrency upon which the application depends.
102Library developers are advised to not use the
103.Fn pthread_getconcurrency
104and
105.Fn pthread_setconcurrency
106functions since their use may conflict with an application's
107use of these functions.
108.Sh STANDARDS
109The
110.Fn pthread_getconcurrency
111and
112.Fn pthread_setconcurrency
113functions conform to
114.St -susv2 .
115