Improve RWSpinLock.h cautionary comment

[folly.git] / folly / MicroSpinLock.h

diff --git a/folly/MicroSpinLock.h b/folly/MicroSpinLock.h
index fde93357bc610238d5ae589a4fd820358f17a7f8..5916dbdc381242842645e531f91e084e0e53b3f3 100644 (file)
--- a/folly/MicroSpinLock.h
+++ b/folly/MicroSpinLock.h
@@ -14,6 +14,22 @@
  * limitations under the License.
  */
 
+/*
+ * N.B. You most likely do _not_ want to use MicroSpinLock or any
+ * other kind of spinlock.
+ *
+ * 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
 
 /*