      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298

    use std::any::Any;
    use std::boxed::Box;
    use std::cell::UnsafeCell;
    use std::error::Error;
    use std::fmt;
    use std::mem;
    use std::ops::{Deref, DerefMut};
    use std::sync::Arc;
    use std::sync::atomic::AtomicUsize;
    use std::sync::atomic::Ordering::SeqCst;

    use {Async, Future, Poll};
    use task::{self, Task};

    /// A type of futures-powered synchronization primitive which is a mutex between
    /// two possible owners.
    ///
    /// This primitive is not as generic as a full-blown mutex but is sufficient for
    /// many use cases where there are only two possible owners of a resource. The
    /// implementation of `BiLock` can be more optimized for just the two possible
    /// owners.
    ///
    /// Note that it's possible to use this lock through a poll-style interface with
    /// the `poll_lock` method but you can also use it as a future with the `lock`
    /// method that consumes a `BiLock` and returns a future that will resolve when
    /// it's locked.
    ///
    /// A `BiLock` is typically used for "split" operations where data which serves
    /// two purposes wants to be split into two to be worked with separately. For
    /// example a TCP stream could be both a reader and a writer or a framing layer
    /// could be both a stream and a sink for messages. A `BiLock` enables splitting
    /// these two and then using each independently in a futures-powered fashion.
    #[derive(Debug)]
    pub struct BiLock<T> {
        inner: Arc<Inner<T>>,
    }

    #[derive(Debug)]
    struct Inner<T> {
        state: AtomicUsize,
        inner: Option<UnsafeCell<T>>,
    }

    unsafe impl<T: Send> Send for Inner<T> {}
    unsafe impl<T: Send> Sync for Inner<T> {}

    impl<T> BiLock<T> {
        /// Creates a new `BiLock` protecting the provided data.
        ///
        /// Two handles to the lock are returned, and these are the only two handles
        /// that will ever be available to the lock. These can then be sent to separate
        /// tasks to be managed there.
        pub fn new(t: T) -> (BiLock<T>, BiLock<T>) {
            let inner = Arc::new(Inner {
                state: AtomicUsize::new(0),
                inner: Some(UnsafeCell::new(t)),
            });

            (BiLock { inner: inner.clone() }, BiLock { inner: inner })
        }

        /// Attempt to acquire this lock, returning `NotReady` if it can't be
        /// acquired.
        ///
        /// This function will acquire the lock in a nonblocking fashion, returning
        /// immediately if the lock is already held. If the lock is successfully
        /// acquired then `Async::Ready` is returned with a value that represents
        /// the locked value (and can be used to access the protected data). The
        /// lock is unlocked when the returned `BiLockGuard` is dropped.
        ///
        /// If the lock is already held then this function will return
        /// `Async::NotReady`. In this case the current task will also be scheduled
        /// to receive a notification when the lock would otherwise become
        /// available.
        ///
        /// # Panics
        ///
        /// This function will panic if called outside the context of a future's
        /// task.
        pub fn poll_lock(&self) -> Async<BiLockGuard<T>> {
            loop {
                match self.inner.state.swap(1, SeqCst) {
                    // Woohoo, we grabbed the lock!
                    0 => return Async::Ready(BiLockGuard { inner: self }),

                    // Oops, someone else has locked the lock
                    1 => {}

                    // A task was previously blocked on this lock, likely our task,
                    // so we need to update that task.
                    n => unsafe {
                        drop(Box::from_raw(n as *mut Task));
                    }
                }

                let me = Box::new(task::current());
                let me = Box::into_raw(me) as usize;

                match self.inner.state.compare_exchange(1, me, SeqCst, SeqCst) {
                    // The lock is still locked, but we've now parked ourselves, so
                    // just report that we're scheduled to receive a notification.
                    Ok(_) => return Async::NotReady,

                    // Oops, looks like the lock was unlocked after our swap above
                    // and before the compare_exchange. Deallocate what we just
                    // allocated and go through the loop again.
                    Err(0) => unsafe {
                        drop(Box::from_raw(me as *mut Task));
                    },

                    // The top of this loop set the previous state to 1, so if we
                    // failed the CAS above then it's because the previous value was
                    // *not* zero or one. This indicates that a task was blocked,
                    // but we're trying to acquire the lock and there's only one
                    // other reference of the lock, so it should be impossible for
                    // that task to ever block itself.
                    Err(n) => panic!("invalid state: {}", n),
                }
            }
        }

        /// Perform a "blocking lock" of this lock, consuming this lock handle and
        /// returning a future to the acquired lock.
        ///
        /// This function consumes the `BiLock<T>` and returns a sentinel future,
        /// `BiLockAcquire<T>`. The returned future will resolve to
        /// `BiLockAcquired<T>` which represents a locked lock similarly to
        /// `BiLockGuard<T>`.
        ///
        /// Note that the returned future will never resolve to an error.
        pub fn lock(self) -> BiLockAcquire<T> {
            BiLockAcquire {
                inner: Some(self),
            }
        }

        /// Attempts to put the two "halves" of a `BiLock<T>` back together and
        /// recover the original value. Succeeds only if the two `BiLock<T>`s
        /// originated from the same call to `BiLock::new`.
        pub fn reunite(self, other: Self) -> Result<T, ReuniteError<T>> {
            if &*self.inner as *const _ == &*other.inner as *const _ {
                drop(other);
                let inner = Arc::try_unwrap(self.inner)
                    .ok()
                    .expect("futures: try_unwrap failed in BiLock<T>::reunite");
                Ok(unsafe { inner.into_inner() })
            } else {
                Err(ReuniteError(self, other))
            }
        }

        fn unlock(&self) {
            match self.inner.state.swap(0, SeqCst) {
                // we've locked the lock, shouldn't be possible for us to see an
                // unlocked lock.
                0 => panic!("invalid unlocked state"),

                // Ok, no one else tried to get the lock, we're done.
                1 => {}

                // Another task has parked themselves on this lock, let's wake them
                // up as its now their turn.
                n => unsafe {
                    Box::from_raw(n as *mut Task).notify();
                }
            }
        }
    }

    impl<T> Inner<T> {
        unsafe fn into_inner(mut self) -> T {
            mem::replace(&mut self.inner, None).unwrap().into_inner()
        }
    }

    impl<T> Drop for Inner<T> {
        fn drop(&mut self) {
            assert_eq!(self.state.load(SeqCst), 0);
        }
    }

    /// Error indicating two `BiLock<T>`s were not two halves of a whole, and
    /// thus could not be `reunite`d.
    pub struct ReuniteError<T>(pub BiLock<T>, pub BiLock<T>);

    impl<T> fmt::Debug for ReuniteError<T> {
        fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
            fmt.debug_tuple("ReuniteError")
                .field(&"...")
                .finish()
        }
    }

    impl<T> fmt::Display for ReuniteError<T> {
        fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
            write!(fmt, "tried to reunite two BiLocks that don't form a pair")
        }
    }

    impl<T: Any> Error for ReuniteError<T> {
        fn description(&self) -> &str {
            "tried to reunite two BiLocks that don't form a pair"
        }
    }

    /// Returned RAII guard from the `poll_lock` method.
    ///
    /// This structure acts as a sentinel to the data in the `BiLock<T>` itself,
    /// implementing `Deref` and `DerefMut` to `T`. When dropped, the lock will be
    /// unlocked.
    #[derive(Debug)]
    pub struct BiLockGuard<'a, T: 'a> {
        inner: &'a BiLock<T>,
    }

    impl<'a, T> Deref for BiLockGuard<'a, T> {
        type Target = T;
        fn deref(&self) -> &T {
            unsafe { &*self.inner.inner.inner.as_ref().unwrap().get() }
        }
    }

    impl<'a, T> DerefMut for BiLockGuard<'a, T> {
        fn deref_mut(&mut self) -> &mut T {
            unsafe { &mut *self.inner.inner.inner.as_ref().unwrap().get() }
        }
    }

    impl<'a, T> Drop for BiLockGuard<'a, T> {
        fn drop(&mut self) {
            self.inner.unlock();
        }
    }

    /// Future returned by `BiLock::lock` which will resolve when the lock is
    /// acquired.
    #[derive(Debug)]
    pub struct BiLockAcquire<T> {
        inner: Option<BiLock<T>>,
    }

    impl<T> Future for BiLockAcquire<T> {
        type Item = BiLockAcquired<T>;
        type Error = ();

        fn poll(&mut self) -> Poll<BiLockAcquired<T>, ()> {
            match self.inner.as_ref().expect("cannot poll after Ready").poll_lock() {
                Async::Ready(r) => {
                    mem::forget(r);
                }
                Async::NotReady => return Ok(Async::NotReady),
            }
            Ok(Async::Ready(BiLockAcquired { inner: self.inner.take() }))
        }
    }

    /// Resolved value of the `BiLockAcquire<T>` future.
    ///
    /// This value, like `BiLockGuard<T>`, is a sentinel to the value `T` through
    /// implementations of `Deref` and `DerefMut`. When dropped will unlock the
    /// lock, and the original unlocked `BiLock<T>` can be recovered through the
    /// `unlock` method.
    #[derive(Debug)]
    pub struct BiLockAcquired<T> {
        inner: Option<BiLock<T>>,
    }

    impl<T> BiLockAcquired<T> {
        /// Recovers the original `BiLock<T>`, unlocking this lock.
        pub fn unlock(mut self) -> BiLock<T> {
            let bi_lock = self.inner.take().unwrap();

            bi_lock.unlock();

            bi_lock
        }
    }

    impl<T> Deref for BiLockAcquired<T> {
        type Target = T;
        fn deref(&self) -> &T {
            unsafe { &*self.inner.as_ref().unwrap().inner.inner.as_ref().unwrap().get() }
        }
    }

    impl<T> DerefMut for BiLockAcquired<T> {
        fn deref_mut(&mut self) -> &mut T {
            unsafe { &mut *self.inner.as_mut().unwrap().inner.inner.as_ref().unwrap().get() }
        }
    }

    impl<T> Drop for BiLockAcquired<T> {
        fn drop(&mut self) {
            if let Some(ref bi_lock) = self.inner {
                bi_lock.unlock();
            }
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)