Reverted commit D3427621

[folly.git] / folly / PicoSpinLock.h

diff --git a/folly/PicoSpinLock.h b/folly/PicoSpinLock.h
index ce87d13eddd6a1db764f0195091e6616533a3d6b..32c5abfb43ae742895a27cde78f9fa802c1eb572 100644 (file)
--- a/folly/PicoSpinLock.h
+++ b/folly/PicoSpinLock.h
@@ -14,7 +14,24 @@
  * limitations under the License.
  */
 
+/*
+ * N.B. You most likely do _not_ want to use PicoSpinLock or any other
+ * kind of spinlock.  Consider MicroLock 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
+#define FOLLY_PICO_SPIN_LOCK_H_
 
 /*
  * @author Keith Adams <kma@fb.com>
@@ -22,16 +39,16 @@
  */
 
 #include <array>
+#include <atomic>
 #include <cinttypes>
-#include <type_traits>
 #include <cstdlib>
-#include <pthread.h>
+#include <folly/Portability.h>
 #include <mutex>
-#include <atomic>
+#include <pthread.h>
+#include <type_traits>
 
 #include <glog/logging.h>
 #include <folly/detail/Sleeper.h>
-#include <folly/Portability.h>
 
 #if !FOLLY_X64 && !FOLLY_A64 && !FOLLY_PPC64
 # error "PicoSpinLock.h is currently x64, aarch64 and ppc64 only."