Add #[must_use] to compare_and_swap

`compare_and_swap` can fail if the value in memory has changed since it
was last read by the writer. In these situations, users will usually
want to retry or abort. While developers are usually aware of this aspect
of CAS, the compiler might as well be helpful and remind the user if
they forget to check if their swap actually occurred.

Author: jonhoo

src/libcore/sync/atomic.rs

@@ -403,6 +403,7 @@ impl AtomicBool {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[cfg(any(stage0, target_has_atomic = "cas"))]
+    #[must_use = "if compare_and_swap does not return `current`, the stored value was not changed"]
     pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> bool {
         match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
             Ok(x) => x,
@@ -824,6 +825,7 @@ impl<T> AtomicPtr<T> {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[cfg(any(stage0, target_has_atomic = "cas"))]
+    #[must_use = "if compare_and_swap does not return `current`, the stored value was not changed"]
     pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> *mut T {
         match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
             Ok(x) => x,
@@ -1182,6 +1184,8 @@ assert_eq!(some_var.load(Ordering::Relaxed), 10);
                 #[inline]
                 #[$stable]
                 #[cfg(any(stage0, target_has_atomic = "cas"))]
+                #[must_use = "if compare_and_swap does not return `current`, \
+                              the stored value was not changed"]
                 pub fn compare_and_swap(&self,
                                         current: $int_type,
                                         new: $int_type,