1 //! Thread parking for Darwin-based systems. 2 //! 3 //! Darwin actually has futex syscalls (`__ulock_wait`/`__ulock_wake`), but they 4 //! cannot be used in `std` because they are non-public (their use will lead to 5 //! rejection from the App Store) and because they are only available starting 6 //! with macOS version 10.12, even though the minimum target version is 10.7. 7 //! 8 //! Therefore, we need to look for other synchronization primitives. Luckily, Darwin 9 //! supports semaphores, which allow us to implement the behaviour we need with 10 //! only one primitive (as opposed to a mutex-condvar pair). We use the semaphore 11 //! provided by libdispatch, as the underlying Mach semaphore is only dubiously 12 //! public. 13 14 use crate::std::pin::Pin; 15 use crate::std::sync::atomic::{ 16 AtomicI8, 17 Ordering::{Acquire, Release}, 18 }; 19 use crate::std::time::Duration; 20 21 type dispatch_semaphore_t = *mut crate::std::ffi::c_void; 22 type dispatch_time_t = u64; 23 24 const DISPATCH_TIME_NOW: dispatch_time_t = 0; 25 const DISPATCH_TIME_FOREVER: dispatch_time_t = !0; 26 27 // Contained in libSystem.dylib, which is linked by default. 28 extern "C" { 29 fn dispatch_time(when: dispatch_time_t, delta: i64) -> dispatch_time_t; 30 fn dispatch_semaphore_create(val: isize) -> dispatch_semaphore_t; 31 fn dispatch_semaphore_wait(dsema: dispatch_semaphore_t, timeout: dispatch_time_t) -> isize; 32 fn dispatch_semaphore_signal(dsema: dispatch_semaphore_t) -> isize; 33 fn dispatch_release(object: *mut crate::std::ffi::c_void); 34 } 35 36 const EMPTY: i8 = 0; 37 const NOTIFIED: i8 = 1; 38 const PARKED: i8 = -1; 39 40 pub struct Parker { 41 semaphore: dispatch_semaphore_t, 42 state: AtomicI8, 43 } 44 45 unsafe impl Sync for Parker {} 46 unsafe impl Send for Parker {} 47 48 impl Parker { 49 pub unsafe fn new_in_place(parker: *mut Parker) { 50 let semaphore = dispatch_semaphore_create(0); 51 assert!( 52 !semaphore.is_null(), 53 "failed to create dispatch semaphore for thread synchronization" 54 ); 55 parker.write(Parker { 56 semaphore, 57 state: AtomicI8::new(EMPTY), 58 }) 59 } 60 61 // Does not need `Pin`, but other implementation do. 62 pub unsafe fn park(self: Pin<&Self>) { 63 // The semaphore counter must be zero at this point, because unparking 64 // threads will not actually increase it until we signalled that we 65 // are waiting. 66 67 // Change NOTIFIED to EMPTY and EMPTY to PARKED. 68 if self.state.fetch_sub(1, Acquire) == NOTIFIED { 69 return; 70 } 71 72 // Another thread may increase the semaphore counter from this point on. 73 // If it is faster than us, we will decrement it again immediately below. 74 // If we are faster, we wait. 75 76 // Ensure that the semaphore counter has actually been decremented, even 77 // if the call timed out for some reason. 78 while dispatch_semaphore_wait(self.semaphore, DISPATCH_TIME_FOREVER) != 0 {} 79 80 // At this point, the semaphore counter is zero again. 81 82 // We were definitely woken up, so we don't need to check the state. 83 // Still, we need to reset the state using a swap to observe the state 84 // change with acquire ordering. 85 self.state.swap(EMPTY, Acquire); 86 } 87 88 // Does not need `Pin`, but other implementation do. 89 pub unsafe fn park_timeout(self: Pin<&Self>, dur: Duration) { 90 if self.state.fetch_sub(1, Acquire) == NOTIFIED { 91 return; 92 } 93 94 let nanos = dur.as_nanos().try_into().unwrap_or(i64::MAX); 95 let timeout = dispatch_time(DISPATCH_TIME_NOW, nanos); 96 97 let timeout = dispatch_semaphore_wait(self.semaphore, timeout) != 0; 98 99 let state = self.state.swap(EMPTY, Acquire); 100 if state == NOTIFIED && timeout { 101 // If the state was NOTIFIED but semaphore_wait returned without 102 // decrementing the count because of a timeout, it means another 103 // thread is about to call semaphore_signal. We must wait for that 104 // to happen to ensure the semaphore count is reset. 105 while dispatch_semaphore_wait(self.semaphore, DISPATCH_TIME_FOREVER) != 0 {} 106 } else { 107 // Either a timeout occurred and we reset the state before any thread 108 // tried to wake us up, or we were woken up and reset the state, 109 // making sure to observe the state change with acquire ordering. 110 // Either way, the semaphore counter is now zero again. 111 } 112 } 113 114 // Does not need `Pin`, but other implementation do. 115 pub fn unpark(self: Pin<&Self>) { 116 let state = self.state.swap(NOTIFIED, Release); 117 if state == PARKED { 118 unsafe { 119 dispatch_semaphore_signal(self.semaphore); 120 } 121 } 122 } 123 } 124 125 impl Drop for Parker { 126 fn drop(&mut self) { 127 // SAFETY: 128 // We always ensure that the semaphore count is reset, so this will 129 // never cause an exception. 130 unsafe { 131 dispatch_release(self.semaphore); 132 } 133 } 134 } 135