1.\" Copyright (c) 2003 Sergey Osokin <osa@FreeBSD.org.ru>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/share/man/man3/pthread_getconcurrency.3,v 1.6 2007/10/22 10:08:00 ru Exp $
26.Dd July 10, 2009
27.Dt PTHREAD_GETCONCURRENCY 3
28.Os
29.Sh NAME
30.Nm pthread_getconcurrency ,
31.Nm pthread_setconcurrency
32.Nd get or set level of concurrency
33.Sh LIBRARY
34.Lb libpthread
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_getconcurrency
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
87The
88.Fn pthread_setconcurrency
89function will fail if:
90.Bl -tag -width Er
91.It Bq Er EINVAL
92The value specified by
93.Fa new_level
94is negative.
95.It Bq Er EAGAIN
96The value specified by
97.Fa new_level
98would cause a system resource to be exceeded.
99.El
100.Sh APPLICATION USAGE
101Use of these functions changes the state of the underlying
102concurrency upon which the application depends.
103Library developers are advised to not use the
104.Fn pthread_getconcurrency
105and
106.Fn pthread_setconcurrency
107functions since their use may conflict with an application's
108use of these functions.
109.Sh STANDARDS
110The
111.Fn pthread_getconcurrency
112and
113.Fn pthread_setconcurrency
114functions conform to
115.St -susv2 .
116