27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1995 IEEE All Rights Reserved
44 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
45 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
46 .\"
47 .TH CONDITION 5 "Jul 20, 1998"
48 .SH NAME
49 condition \- concepts related to condition variables
50 .SH DESCRIPTION
51 .sp
52 .LP
53 Occasionally, a thread running within a mutex needs to wait for an event, in
54 which case it blocks or sleeps. When a thread is waiting for another thread to
55 communicate its disposition, it uses a condition variable in conjunction with a
56 mutex. Although a mutex is exclusive and the code it protects is sharable (at
57 certain moments), condition variables enable the synchronization of differing
58 events that share a mutex, but not necessarily data. Several condition
59 variables may be used by threads to signal each other when a task is complete,
60 which then allows the next waiting thread to take ownership of the mutex.
61 .sp
62 .LP
63 A condition variable enables threads to atomically block and test the condition
64 under the protection of a mutual exclusion lock (mutex) until the condition is
65 satisfied. If the condition is false, a thread blocks on a condition variable
66 and atomically releases the mutex that is waiting for the condition to change.
67 If another thread changes the condition, it may wake up waiting threads by
68 signaling the associated condition variable. The waiting threads, upon
69 awakening, reacquire the mutex and re-evaluate the condition.
70 .SS "Initialize"
71 .sp
72 .LP
73 Condition variables and mutexes should be global. Condition variables that are
74 allocated in writable memory can synchronize threads among processes if they
75 are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized
76 for this purpose.
77 .sp
78 .LP
79 The scope of a condition variable is either intra-process or inter-process.
80 This is dependent upon whether the argument is passed implicitly or explicitly
81 to the initialization of that condition variable. A condition variable does
82 not need to be explicitly initialized. A condition variable is initialized with
83 all zeros, by default, and its scope is set to within the calling process. For
84 inter-process synchronization, a condition variable must be initialized once,
85 and only once, before use.
86 .sp
87 .LP
88 A condition variable must not be simultaneously initialized by multiple threads
89 or re-initialized while in use by other threads.
90 .sp
91 .LP
92 Condition variables attributes may be set to the default or customized at
93 initialization. POSIX threads even allow the default values to be customized.
94 Establishing these attributes varies depending upon whether POSIX or Solaris
95 threads are used. Similar to the distinctions between POSIX and Solaris thread
96 creation, POSIX condition variables implement the default, intra-process,
97 unless an attribute object is modified for inter-process prior to the
98 initialization of the condition variable. Solaris condition variables also
99 implement as the default, intra-process; however, they set this attribute
100 according to the argument, \fItype\fR, passed to their initialization function.
101 .SS "Condition Wait"
102 .sp
103 .LP
104 The condition wait interface allows a thread to wait for a condition and
105 atomically release the associated mutex that it needs to hold to check the
106 condition. The thread waits for another thread to make the condition true and
107 that thread's resulting call to signal and wakeup the waiting thread.
108 .SS "Condition Signaling"
109 .sp
110 .LP
111 A condition signal allows a thread to unblock the next thread waiting on the
112 condition variable, whereas, a condition broadcast allows a thread to unblock
113 all threads waiting on the condition variable.
114 .SS "Destroy"
115 .sp
116 .LP
117 The condition destroy functions destroy any state, but not the space,
118 associated with the condition variable.
119 .SH ATTRIBUTES
120 .sp
121 .LP
122 See \fBattributes\fR(5) for descriptions of the following attributes:
123 .sp
124
125 .sp
126 .TS
127 box;
128 c | c
129 l | l .
130 ATTRIBUTE TYPE ATTRIBUTE VALUE
131 _
132 MT-Level MT-Safe
133 .TE
134
135 .SH SEE ALSO
136 .sp
137 .LP
138 \fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2),
139 \fBcond_broadcast\fR(3C), \fBcond_destroy\fR(3C), \fBcond_init\fR(3C),
140 \fBcond_signal\fR(3C), \fBcond_timedwait\fR(3C), \fBcond_wait\fR(3C),
141 \fBpthread_cond_broadcast\fR(3C), \fBpthread_cond_destroy\fR(3C),
142 \fBpthread_cond_init\fR(3C), \fBpthread_cond_signal\fR(3C),
143 \fBpthread_cond_timedwait\fR(3C), \fBpthread_cond_wait\fR(3C),
144 \fBpthread_condattr_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
145 \fBmutex\fR(5), \fBstandards\fR(5)
146 .SH NOTES
147 .sp
148 .LP
149 If more than one thread is blocked on a condition variable, the order in which
150 threads are unblocked is determined by the scheduling policy.
151 .sp
152 .LP
153 \fBUSYNC_THREAD\fR does not support multiple mapplings to the same logical
154 synch object. If you need to \fBmmap()\fR a synch object to different locations
155 within the same address space, then the synch object should be initialized as a
156 shared object \fBUSYNC_PROCESS\fR for Solaris, and
157 \fBPTHREAD_PROCESS_PRIVATE\fR for POSIX.
|
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1995 IEEE All Rights Reserved
44 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
45 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
46 .\"
47 .TH CONDITION 5 "May 16, 2020"
48 .SH NAME
49 condition \- concepts related to condition variables
50 .SH DESCRIPTION
51 Occasionally, a thread running within a mutex needs to wait for an event, in
52 which case it blocks or sleeps. When a thread is waiting for another thread to
53 communicate its disposition, it uses a condition variable in conjunction with a
54 mutex. Although a mutex is exclusive and the code it protects is sharable (at
55 certain moments), condition variables enable the synchronization of differing
56 events that share a mutex, but not necessarily data. Several condition
57 variables may be used by threads to signal each other when a task is complete,
58 which then allows the next waiting thread to take ownership of the mutex.
59 .sp
60 .LP
61 A condition variable enables threads to atomically block and test the condition
62 under the protection of a mutual exclusion lock (mutex) until the condition is
63 satisfied. If the condition is false, a thread blocks on a condition variable
64 and atomically releases the mutex that is waiting for the condition to change.
65 If another thread changes the condition, it may wake up waiting threads by
66 signaling the associated condition variable. The waiting threads, upon
67 awakening, reacquire the mutex and re-evaluate the condition.
68 .SS "Initialize"
69 Condition variables and mutexes should be global. Condition variables that are
70 allocated in writable memory can synchronize threads among processes if they
71 are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized
72 for this purpose.
73 .sp
74 .LP
75 The scope of a condition variable is either intra-process or inter-process.
76 This is dependent upon whether the argument is passed implicitly or explicitly
77 to the initialization of that condition variable. A condition variable does
78 not need to be explicitly initialized. A condition variable is initialized with
79 all zeros, by default, and its scope is set to within the calling process. For
80 inter-process synchronization, a condition variable must be initialized once,
81 and only once, before use.
82 .sp
83 .LP
84 A condition variable must not be simultaneously initialized by multiple threads
85 or re-initialized while in use by other threads.
86 .sp
87 .LP
88 Condition variables attributes may be set to the default or customized at
89 initialization. POSIX threads even allow the default values to be customized.
90 Establishing these attributes varies depending upon whether POSIX or Solaris
91 threads are used. Similar to the distinctions between POSIX and Solaris thread
92 creation, POSIX condition variables implement the default, intra-process,
93 unless an attribute object is modified for inter-process prior to the
94 initialization of the condition variable. Solaris condition variables also
95 implement as the default, intra-process; however, they set this attribute
96 according to the argument, \fItype\fR, passed to their initialization function.
97 .SS "Condition Wait"
98 The condition wait interface allows a thread to wait for a condition and
99 atomically release the associated mutex that it needs to hold to check the
100 condition. The thread waits for another thread to make the condition true and
101 that thread's resulting call to signal and wakeup the waiting thread.
102 .SS "Condition Signaling"
103 A condition signal allows a thread to unblock the next thread waiting on the
104 condition variable, whereas, a condition broadcast allows a thread to unblock
105 all threads waiting on the condition variable.
106 .SS "Destroy"
107 The condition destroy functions destroy any state, but not the space,
108 associated with the condition variable.
109 .SH ATTRIBUTES
110 See \fBattributes\fR(5) for descriptions of the following attributes:
111 .sp
112
113 .sp
114 .TS
115 box;
116 c | c
117 l | l .
118 ATTRIBUTE TYPE ATTRIBUTE VALUE
119 _
120 MT-Level MT-Safe
121 .TE
122
123 .SH SEE ALSO
124 \fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2),
125 \fBcond_broadcast\fR(3C), \fBcond_destroy\fR(3C), \fBcond_init\fR(3C),
126 \fBcond_signal\fR(3C), \fBcond_timedwait\fR(3C), \fBcond_wait\fR(3C),
127 \fBpthread_cond_broadcast\fR(3C), \fBpthread_cond_destroy\fR(3C),
128 \fBpthread_cond_init\fR(3C), \fBpthread_cond_signal\fR(3C),
129 \fBpthread_cond_timedwait\fR(3C), \fBpthread_cond_wait\fR(3C),
130 \fBpthread_condattr_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
131 \fBmutex\fR(5), \fBstandards\fR(5)
132 .SH NOTES
133 If more than one thread is blocked on a condition variable, the order in which
134 threads are unblocked is determined by the scheduling policy.
135 .sp
136 .LP
137 \fBUSYNC_THREAD\fR does not support multiple mappings to the same logical
138 synch object. If you need to \fBmmap()\fR a synch object to different locations
139 within the same address space, then the synch object should be initialized as a
140 shared object \fBUSYNC_PROCESS\fR for Solaris, and
141 \fBPTHREAD_PROCESS_PRIVATE\fR for POSIX.
|