1 .\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in
14 .\" the documentation and/or other materials provided with the
16 .\" 3. Neither the name of The DragonFly Project nor the names of its
17 .\" contributors may be used to endorse or promote products derived
18 .\" from this software without specific, prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nd kernel support for userland mutexes
45 .Fn umtx_sleep "volatile const int *ptr" "int value" "int timeout"
47 .Fn umtx_wakeup "volatile const int *ptr" "int count"
51 system call will put the calling process to sleep for
53 microseconds if the contents of the specified pointer matches
55 Specifying a timeout of 0 indicates an indefinite timeout.
56 The comparison is not atomic with the sleep but is properly
57 interlocked against another process calling
59 In particular, while it is possible for two userland threads to race, one
60 going to sleep simultaneously with another releasing the mutex, this condition
61 is caught when the second userland thread calls
63 after releasing the contended mutex.
67 has no specific limitation other than what fits in the signed integer.
68 A negative timeout will return
71 WARNING! In order to properly interlock against fork(), this function will
72 do an atomic read-modify-write on the underlying memory by atomically
73 adding the value 0 to it.
77 system call will wakeup the specified number of processes sleeping
80 on the specified user address. A count of 0 will wake up all sleeping
81 processes. This function may wake up more processes then the specified
82 count but will never wake up fewer processes (unless there are simply not
83 that many currently sleeping on the address). The current
85 implementation optimized the count = 1 case but otherwise just wakes up
86 all processes sleeping on the address.
88 Kernel support for userland mutexes is based on the physical memory backing
90 That is, the kernel will typically construct a sleep id based on the
91 underlying physical memory address.
92 Two userland programs may use this facility through
96 or light weight process-based shared memory.
97 It is important to note that the kernel does not
98 take responsibility for adjusting the contents of the mutex or for the
99 userland implementation of the mutex.
102 does not restart in case of a signal, even if the signal specifies
103 that system calls should restart.
105 Various operating system events can cause
107 to return prematurely, with the contents of the mutex unchanged relative
108 to the compare value. Callers must be able to deal with such returns.
111 will return 0 if it successfully slept and was then woken up. Otherwise
112 it will return -1 and set
117 will generally return 0 unless the address is bad.
119 .Bd -literal -compact
122 userland_get_mutex(struct umtx *mtx)
129 if (atomic_fcmpset_int(&mtx->lock, &v, 1))
131 } else if (atomic_fcmpset_int(&mtx->lock, &v, 2)) {
132 umtx_sleep(&mtx->lock, 2, 0);
138 userland_rel_mutex(struct umtx *mtx)
142 v = atomic_swap_int(&mtx->lock, 0);
144 umtx_wakeup(&mtx->lock, 1);
148 This function can return -1 with errno set to
150 early and even if no timeout is specified due to the kernel failsafe
152 The caller is advised to track the timeout independently using
155 This function can return -1 with errno set to
157 and it is up to the caller to loop if the caller's own API disallows
161 This function can also return -1 with errno set to
163 due to internal kernel effects.
165 This function can return without error when woken up via internal
166 kernel effects and not necessarily just by a
170 Because the kernel will always use the underlying physical address
171 for its tsleep/wakeup id (e.g. which is required to properly supported
172 memory-mapped locks shared between processes), certain actions taken by
173 the program and/or by the kernel can disrupt synchronization between
177 The kernel is responsible for handling
179 actions, and will typically wakeup all blocked
181 for all threads of a process upon any thread forking.
182 However, other actions such as pagein and pageout can also desynchronize
184 To deal with these actions, the kernel typically implements a failsafe
185 timeout of around 2 seconds for
187 To properly resynchronize the physical address, ALL threads blocking on
188 the address should perform a modifying operation on the underlying memory
189 before re-entering the wait state,
190 or otherwise be willing to incur the failsafe timeout as their recovery
197 possibly did not match
199 .It Bq Er EWOULDBLOCK
200 The specified timeout occurred,
201 or a kernel-defined failsafe timeout occurred,
202 or the kernel requires a retry due to a copy-on-write / fork operation.
203 Callers should not assume that the precise requested timeout occurred
204 when this error is returned, and this error can be returned even
205 when no timeout is specified.
209 call was interrupted by a signal.
211 An invalid parameter (typically an invalid timeout) was specified.
220 function calls first appeared in