priomutex:  a mutex where waiting threads specify a priority
============================================================

The API is very similar to std::sync::Mutex.  The key difference, of course, is
that lock() takes a priority.  If multiple threads are waiting for the mutex
when it's freed, the one which gave the highest priorty will recieve it.

    impl<T> Mutex<T> {
        fn new(data: T) -> Mutex<T>;
        fn lock(&self, prio: usize) -> LockResult<MutexGuard<T>>;
        fn try_lock(&self) -> TryLockResult<MutexGuard<T>>;
    }

    impl<T> Drop for MutexGuard<T>;      // Releases the lock
    impl<T> Deref for MutexGuard<T>;     // For accessing your data
    impl<T> DerefMut for MutexGuard<T>;  // For accessing your data

This crate also includes a high-performance variant in the spin_one module,
which spins the highest-priority waiting thread.  This makes releasing the
mutex very fast, because it never needs to do any syscalls.


Status
------

There is no unsafe code used in either variant, so there's no possibility of
two threads holding the mutex at the same time.  Bugs may lead to deadlocks or
non-priority-order locking, however.  I'm not currently aware of any such bugs.

Benchmarking locking time is difficult.  Release time, however, can be reliably
measured:

    simple:   2887 ns
    spin_one:  248 ns

(Intel Core i7-4790K CPU @ 4.00GHz, max_cstate = 0)


Licence
-------

Licensed under either of the following, at your option:

 * Apache Licence 2.0 (see LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT licence (see LICENSE-MIT or http://opensource.org/licenses/MIT)

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.