auto merge of #15781 : alexcrichton/rust/issue-15758, r=bblum

Semaphores are not currently designed to handle this case correctly, leading to
very strange behavior. Semaphores as written are intended to count *resources*
and it's not possible to have a negative number of resources.

This alters the behavior and documentation to note that the task will be failed
if the initial count is 0.

Closes #15758

Author: bors

src/libsync/raw.rs

@@ -109,6 +109,8 @@ struct SemGuard<'a, Q> {
 
 impl<Q: Send> Sem<Q> {
     fn new(count: int, q: Q) -> Sem<Q> {
+        assert!(count >= 0,
+                "semaphores cannot be initialized with negative values");
         Sem {
             lock: mutex::Mutex::new(),
             inner: Unsafe::new(SemInner {
@@ -364,6 +366,10 @@ pub struct SemaphoreGuard<'a> {
 
 impl Semaphore {
     /// Create a new semaphore with the specified count.
+    ///
+    /// # Failure
+    ///
+    /// This function will fail if `count` is negative.
     pub fn new(count: int) -> Semaphore {
         Semaphore { sem: Sem::new(count, ()) }
     }
@@ -637,6 +643,11 @@ mod tests {
         let _g = s.access();
     }
     #[test]
+    #[should_fail]
+    fn test_sem_basic2() {
+        Semaphore::new(-1);
+    }
+    #[test]
     fn test_sem_as_mutex() {
         let s = Arc::new(Semaphore::new(1));
         let s2 = s.clone();