An intro to the upgrade mutex in the Synchronized docs

[folly.git] / folly / SpinLock.h

diff --git a/folly/SpinLock.h b/folly/SpinLock.h
index 2e2356c938e76f9fb45ab50f06ea8618a4586e45..48d20f1af346a8687356aff4f40f028602865954 100644 (file)
--- a/folly/SpinLock.h
+++ b/folly/SpinLock.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014 Facebook, Inc.
+ * Copyright 2016 Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,8 +14,26 @@
  * limitations under the License.
  */
 
+/*
+ * N.B. You most likely do _not_ want to use SpinLock or any other
+ * kind of spinlock.  Use std::mutex instead.
+ *
+ * In short, spinlocks in preemptive multi-tasking operating systems
+ * have serious problems and fast mutexes like std::mutex are almost
+ * certainly the better choice, because letting the OS scheduler put a
+ * thread to sleep is better for system responsiveness and throughput
+ * than wasting a timeslice repeatedly querying a lock held by a
+ * thread that's blocked, and you can't prevent userspace
+ * programs blocking.
+ *
+ * Spinlocks in an operating system kernel make much more sense than
+ * they do in userspace.
+ */
+
 #pragma once
 
+#include <type_traits>
+
 #include <folly/detail/SpinLockImpl.h>
 
 namespace folly {
@@ -25,9 +43,9 @@ typedef SpinLockMslImpl SpinLock;
 #elif __APPLE__
 typedef SpinLockAppleImpl SpinLock;
 #elif FOLLY_HAVE_PTHREAD_SPINLOCK_T
-typedef SpinLockPthreadMutexImpl SpinLock;
-#else
 typedef SpinLockPthreadImpl SpinLock;
+#else
+typedef SpinLockPthreadMutexImpl SpinLock;
 #endif
 
 template <typename LOCK>