Lines Matching full:the

1 .\" Copyright (c) 2016 The FreeBSD Foundation
5 .\" from the FreeBSD Foundation.
8 .\" 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 the
14 .\"    documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 uses the syscall to implement
52 The operations, performed by the
55 by the following structures.
63 Allow selection of the process-shared sleep queue for the thread sleep
64 container, when the lock ownership cannot be granted immediately,
65 and the operation must sleep.
67 the attributes of the memory mapping which contains the first byte of
70 Otherwise, if the flag is not specified, the process-private sleep queue
71 is selected regardless of the memory mapping attributes, as an optimization.
73 See the
90 field is the actual lock.
91 It contains either the thread identifier of the lock owner in the
92 locked state, or zero when the lock is unowned.
93 The highest bit set indicates that there is contention on the lock.
97 Zero, the value stored in the unowned lock.
101 A thread owning the robust mutex terminated.
110 field may contain the following umutex-specific flags, in addition to
122 Mutex is robust, as described in the
130 In the manual page, mutexes not having
138 with the given key.
140 For priority protected mutexes, the
145 is the ceiling value for the mutex, as specified by
147 for the
152 is used only for the unlock of a priority protected mutex, when
153 unlock is done in an order other than the reversed lock order.
156 must contain the ceiling value for the last locked priority protected
158 If, instead, the unlocking mutex was the last priority propagated
159 mutex locked by the thread,
162 This is required because kernel does not maintain the ordered lock list.
174 value indicates that there are in-kernel waiters for the condition,
175 executing the
182 Only the common flags
188 member provides the clock identifier to use for timeout, when the
190 request has both the
192 flag and the timeout specified.
235 field is the actual lock.
236 It contains both the flags and counter of the read locks which were
238 Names of the
249 Returns the count of currently granted read locks.
252 At any given time there may be only one thread to which the writer lock
253 is granted on the
256 Or, at the given time, up to
258 threads may be granted the read lock simultaneously, but write lock is
261 The following flags for the
265 are defined, in addition to the common flags:
280 members contain the count of threads which are sleeping in kernel,
281 waiting for the associated request type to be granted.
282 The fields are used by kernel to update the
286 flags of the
301 represents the locked state.
307 word, besides the counter of posts (unlocks), also contains the
313 macro, applied to the
315 word, returns the current semaphore counter, which is the number of posts
316 issued on the semaphore.
318 The following bits for the
322 are defined, in addition to the common flags:
338 operations allow the blocking time to be limited, failing the request
339 if it cannot be satisfied in the specified time period.
340 The timeout is specified by passing either the address of
344 as the
348 They are distinguished by the
350 value, which must be equal to the size of the structure pointed to by
357 member specifies the time when the timeout should occur.
360 are shared with the
362 argument to the
365 and use the same underlying clocks.
366 The specified clock is used to obtain the current time value.
367 Interval counting is always performed by the monotonic wall clock.
371 argument allows the following flags to further define the timeout behaviour:
376 value is the absolute time.
377 The thread will be unblocked and the request failed when specified
378 clock value is equal or exceeds the
381 If the flag is absent, the timeout value is relative, that is the amount
382 of time, measured by the monotonic wall clock from the moment of the request
387 When a locking request cannot be immediately satisfied, the thread is
390 which is a non-runnable state terminated by the
395 variant which returns an error rather than sleeping if the lock cannot
399 provides requests which explicitly put the thread to sleep.
406 is defined as the physical address of some variable.
407 Note that the
411 This mechanism enables the construction of
415 A related attribute of the key is shareability.
416 Some requests always interpret keys as private for the current process,
417 creating sleep queues with the scope of the current process even if
419 Others either select the shareability automatically from the
420 mapping attributes, or take additional input as the
423 This is done as optimization, allowing the lock scope to be limited
424 regardless of the kind of backing memory.
426 Only the address of the start byte of the variable specified as key is
428 The size of the variable does not matter, so, for example, sleep on the same
435 The last attribute of the key is the object type.
438 primitives, even when the physical address of the key is same.
441 the highest priority threads that have been blocked for the longest on
449 A robust umutex must have the
453 On thread termination, the kernel walks two lists of mutexes.
458 The link to next element is provided by the
460 member of the
463 Robust list processing is aborted if the kernel finds a mutex
464 with any of the following conditions:
471 not owned by the current thread, except when the mutex is pointed to
472 by the
474 member of the
476 registered for the current thread
480 read of the umutex memory faults
487 Every mutex in both lists is unlocked as if the
489 request is performed on it, but instead of the
491 value, the
493 field is written with the
496 When a mutex in the
498 state is locked by kernel due to the
502 requests, the lock is granted and
506 Also, the kernel handles the
509 .Dv the m_owner
510 field specially, always returning the
512 error for lock attempts, without granting the lock.
514 The following operations, requested by the
516 argument to the function, are implemented:
520 The arguments for the request are:
526 Current value of the
530 The current value of the variable pointed to by the
532 argument is compared with the
534 If they are equal, the requesting thread is put to interruptible sleep
535 until woken up or the optionally specified timeout expires.
542 the request is guaranteed to not miss the wakeup,
545 The physical address of memory where the
549 The read of the current value of the
552 In particular, it is the user's duty to ensure the lock acquire
553 and release memory semantics, if the
560 An unblocked signal delivered during the wait always results in sleep
565 Optionally, a timeout for the request may be specified.
567 Wake the threads possibly sleeping due to
569 The arguments for the request are:
583 The arguments to the request are:
586 Pointer to the umutex.
589 Operates same as the
593 instead of sleeping if the lock cannot be obtained immediately.
596 The arguments to the request are:
599 Pointer to the umutex.
602 Locking is performed by writing the current thread id into the
604 word of the
606 The write is atomic, preserves the
608 contention indicator, and provides the acquire barrier for
611 If the lock cannot be obtained immediately because another thread owns
612 the lock, the current thread is put to sleep, with
615 Upon wake up, the lock conditions are re-tested.
617 The request adheres to the priority protection or inheritance protocol
618 of the mutex, specified by the
624 Optionally, a timeout for the request may be specified.
627 An unblocked signal delivered during the wait always results in sleep
635 The arguments to the request are:
638 Pointer to the umutex.
641 Unlocks the mutex, by writing
645 word of the
649 If there are threads sleeping in the sleep queue associated with the
651 If more than one thread sleeps in the sleep queue, the
653 bit is set together with the write of the
658 The request adheres to the priority protection or inheritance protocol
659 of the mutex, specified by the
664 See description of the
666 member of the
668 structure for additional details of the request operation on the
671 Set ceiling for the priority protected umutex.
672 The arguments to the request are:
675 Pointer to the umutex.
683 and the update was successful, the previous ceiling value is
684 written to the location pointed to by
688 The request locks the umutex pointed to by the
690 parameter, waiting for the lock if not immediately available.
691 After the lock is obtained, the new ceiling value
693 is written to the
695 member of the
697 after which the umutex is unlocked.
699 The locking does not adhere to the priority protect protocol,
700 to conform to the
702 requirements for the
707 The arguments to the request are:
710 Pointer to the
715 Pointer to the umutex.
722 The request must be issued by the thread owning the mutex pointed to
723 by the
728 member of the
730 pointed to by the
732 argument, is set to an arbitrary non-zero value, after which the
734 mutex is unlocked (following the appropriate protocol), and
735 the current thread is put to sleep on the sleep queue keyed by
744 sent between mutex unlock and putting the current thread on the sleep queue.
746 Upon wakeup, if the timeout expired and no other threads are sleeping in
747 the same sleep queue, the
750 After wakeup, the
762 Optionally, a timeout for the request may be specified.
763 Unlike other requests, the timeout value is specified directly by a
765 pointed to by the
768 If the
770 flag is provided, the timeout uses the clock from the
772 member of the
779 is used, regardless of the clock identifier possibly specified in the
781 If the
783 flag is supplied, the timeout specifies absolute time value, otherwise
793 The arguments to the request are:
800 The request wakes up at most one thread sleeping on the sleep queue keyed
801 by the
804 If the woken up thread was the last on the sleep queue, the
806 member of the
811 The arguments to the request are:
818 The request wakes up all threads sleeping on the sleep queue keyed by the
823 member of the
829 but the type of the variable pointed to by
838 The arguments to the request are:
841 Pointer to the lock (of type
846 The valid flags in the
854 The request obtains the read lock on the specified
856 by incrementing the count of readers in the
858 word of the structure.
859 If the
861 bit is set in the word
865 In this case the current thread is put to sleep until it makes sense to
868 If the
870 flag is set either in the
872 word of the structure, or in the
874 argument of the request, the presence of the threads trying to obtain
875 the write lock on the same structure does not prevent the current thread
876 from trying to obtain the read lock.
877 Otherwise, if the flag is not set, and the
882 Instead it sets the
884 in the
887 Upon wakeup, the locking conditions are re-evaluated.
889 Optionally, a timeout for the request may be specified.
892 An unblocked signal delivered during the wait always results in sleep
900 The arguments to the request are:
903 Pointer to the lock (of type
908 The request obtains a write lock on the specified
910 by setting the
912 bit in the
914 word of the structure.
915 If there is already a write lock owner, as indicated by the
918 by the read-lock counter, the current thread does not attempt to
919 obtain the write-lock.
920 Instead it sets the
922 in the
925 Upon wakeup, the locking conditions are re-evaluated.
927 Optionally, a timeout for the request may be specified.
930 An unblocked signal delivered during the wait always results in sleep
936 The arguments to the request are:
939 Pointer to the lock (of type
944 The unlock type (read or write) is determined by the
946 Note that the
948 does not save information about the identity of the thread which
949 acquired the lock.
951 If there are pending writers after the unlock, and the
953 flag is not set in the
955 member of the
957 structure, one writer is woken up, selected as described in the
960 If the
965 If there are no pending writers, or, in the case that the
971 but unconditionally select the process-private sleep queue.
975 but unconditionally select the process-private sleep queue.
978 The arguments to the request are:
981 Address of the mutex.
984 Similarly to the
986 put the requesting thread to sleep if the mutex lock cannot be obtained
990 bit is set in the
992 word of the mutex to indicate that there is a waiter, before the thread
993 is added to the sleep queue.
994 Unlike the
996 request, the lock is not obtained.
1001 Optionally, a timeout for the request may be specified.
1004 An unblocked signal delivered during the wait always results in sleep
1008 A request without a timeout automatically restarts if the signal disposition
1009 requested restart via the
1017 The arguments to the request are:
1020 Pointer to the array of pointers.
1022 Number of elements in the array pointed to by
1026 For each element in the array pointed to by
1028 wakes up all threads waiting on the
1030 sleep queue with the key
1031 being the byte addressed by the array element.
1034 The arguments for the request are:
1037 Pointer to the umutex.
1040 If the
1042 word of the mutex pointed to by the
1046 set, clear the bit and wake up one waiter in the sleep queue associated
1047 with the byte addressed by the
1050 Only normal mutexes are supported by the request.
1056 That is, the
1061 so that another thread can lock, unlock and destroy the mutex
1062 (if no other thread uses the mutex afterwards).
1063 Clearing the
1068 The arguments for the request are:
1071 Pointer to the umutex.
1076 The request does not read the
1078 member of the
1080 instead, the
1082 argument supplies flag information, in particular, to determine the
1083 sleep queue where the waiters are found for wake up.
1085 If the mutex is unowned, one waiter is woken up.
1087 If the mutex memory cannot be accessed, all waiters are woken up.
1089 If there is more than one waiter on the sleep queue, or there is only
1090 one waiter but the mutex is owned by a thread, the
1092 bit is set in the
1094 word of the
1098 The arguments to the request are:
1101 Pointer to the semaphore (of type
1104 Size of the memory passed in via the
1114 Put the requesting thread onto a sleep queue if the semaphore counter
1116 If the thread is put to sleep, the
1118 bit is set in the
1123 indicating the semaphore is available (non-zero count due to post),
1125 The return does not guarantee that the semaphore is available,
1126 nor does it consume the semaphore lock on successful return.
1128 Optionally, a timeout for the request may be specified.
1138 was not set, and the operation was interrupted and the caller passed in a
1142 following the initial
1144 then the
1146 is updated to contain the unslept amount.
1149 The arguments to the request are:
1152 Pointer to the semaphore (of type
1156 The request wakes up one waiter for the semaphore lock.
1157 The function does not increment the semaphore lock count.
1158 If the
1160 bit was set in the
1162 word, and the last sleeping thread was woken up, the bit is cleared.
1168 which can be attached to a byte of physical memory, mapped into the
1175 argument specifies the sub-request of the
1180 Creates the anonymous shared memory object, which can be looked up
1181 with the specified key
1183 If the object associated with the
1187 On success, the file descriptor referencing the object is returned.
1188 The descriptor can be used for mapping the object using
1199 De-associate the shared object with the specified key
1201 The object is destroyed after the last open file descriptor is closed
1202 and the last mapping for it is destroyed.
1204 Checks whether there is a live shared object associated with the
1208 This request is an optimization of the
1211 It is cheaper when only the liveness of the associated object is asked
1212 for, since no file descriptor is installed in the process fd table
1218 argument specifies the virtual address, which backing physical memory
1219 byte identity is used as a key for the anonymous shared object
1222 Register the list heads for the current thread's robust mutex lists.
1223 The arguments to the request are:
1226 Size of the structure passed in the
1230 Pointer to the structure of type
1245 member contains address of the first element in the list of locked
1249 member contains address of the first element in the list of locked
1252 termination of the shared list on fork, in the child.
1256 contains a pointer to the mutex which might be locked in nearby future,
1258 It is typically set by the lock or unlock mutex implementation code
1259 around the whole operation, since lists can be only changed race-free
1260 when the thread owns the mutex.
1261 The kernel inspects the
1263 in addition to walking the shared and private lists.
1264 Also, the mutex pointed to by
1266 is handled more loosely at the thread termination time,
1267 than other mutexes on the list.
1268 That mutex is allowed to be not owned by the current thread,
1274 Writes out the current value of minimal umtx operations timeout,
1275 in nanoseconds, into the long integer variable pointed to by
1278 Set the minimal amount of time, in nanoseconds, the thread is required
1280 The value is taken from the
1282 argument of the call.
1292 Request i386 ABI compatibility from the native
1320 Request non-i386, 32-bit ABI compatibility from the native
1364 sub-requests of the
1372 On error \-1 is returned, and the
1374 variable is set to indicate the error.
1378 operations can fail with the following errors:
1381 One of the arguments point to invalid memory.
1383 The clock identifier, specified for the
1385 timeout parameter, or in the
1391 The type of the mutex, encoded by the
1399 member of the
1401 has changed the lock owner thread identifier during unlock.
1419 argument for the
1427 The new ceiling value for the
1429 request, or one or more of the values read from the
1434 Unlock attempted on an object not owned by the current thread.
1436 The lock was requested on an umutex where the
1438 field was set to the
1441 The lock was granted to the caller, so this error in fact
1446 field is equal to the
1449 The lock was not granted to the caller.
1451 The shared memory object, associated with the address passed to the
1457 For the
1462 sub-requests of the
1464 request, there is no shared memory object associated with the provided key.
1468 sub-request of the
1470 request cannot be satisfied, because allocation of the shared memory object
1471 would exceed the
1478 were already granted ownership of the given
1482 A try mutex lock operation was not able to obtain the lock.
1484 The request specified a timeout in the
1488 arguments, and timed out before obtaining the lock or being woken up.
1497 is handled by usual adjustment of the instruction counter.
1515 system call is non-standard and is used by the
1522 A window between a unlocking robust mutex and resetting the pointer in the
1524 member of the registered
1526 allows another thread to destroy the mutex, thus making the kernel inspect
1532 A possible fix for the current implementation is to strengthen the checks
1534 that the mutex memory is mapped from a shared memory object allocated
1535 by the
1538 This is not done because it is believed that the race is adequately
1539 covered by other consistency checks, while adding the check would