From 2438389c75a97d8114e46c428c887afcba087c6b Mon Sep 17 00:00:00 2001 From: Lorin Hochstein Date: Fri, 2 Mar 2012 09:39:36 -0500 Subject: [PATCH] Added docs on MySQL queries blocking main thread. Added to the RST docs to describe how queries to MySQL will block a nova service. Change-Id: I4ae209e2827978cc5469162d386197f2e46b342d --- .mailmap | 1 + Authors | 2 +- doc/source/devref/threading.rst | 46 ++++++++++++++++++++++++++++----- 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/.mailmap b/.mailmap index 468fe89df..9202332c6 100644 --- a/.mailmap +++ b/.mailmap @@ -38,6 +38,7 @@ + Masumoto diff --git a/Authors b/Authors index 8db7ad8a6..dc83d82e8 100644 --- a/Authors +++ b/Authors @@ -112,7 +112,7 @@ Koji Iida Liam Kelleher Likitha Shetty Loganathan Parthipan -Lorin Hochstein +Lorin Hochstein Lvov Maxim Mandell Degerness Mark McLoughlin diff --git a/doc/source/devref/threading.rst b/doc/source/devref/threading.rst index e499f47e1..1c8eb5b95 100644 --- a/doc/source/devref/threading.rst +++ b/doc/source/devref/threading.rst @@ -1,17 +1,51 @@ Threading model =============== -All OpenStack services use *green thread* model of threading, implemented -through using the Python `eventlet `_ and +All OpenStack services use *green thread* model of threading, implemented +through using the Python `eventlet `_ and `greenlet `_ libraries. -Green threads use a cooperative model of threading: thread context -switches can only occur when specific eventlet or greenlet library calls are -made (e.g., sleep, certain I/O calls). From the operating system's point of +Green threads use a cooperative model of threading: thread context +switches can only occur when specific eventlet or greenlet library calls are +made (e.g., sleep, certain I/O calls). From the operating system's point of view, each OpenStack service runs in a single thread. The use of green threads reduces the likelihood of race conditions, but does -not completely eliminate them. In some cases, you may need to use the +not completely eliminate them. In some cases, you may need to use the ``@utils.synchronized(...)`` decorator to avoid races. +In addition, since there is only one operating system thread, a call that +blocks that main thread will block the entire process. +Yielding the thread in long-running tasks +----------------------------------------- +If a code path takes a long time to execute and does not contain any methods +that trigger an eventlet context switch, the long-running thread will block +any pending threads. + +This scenario can be avoided by adding calls to the eventlet sleep method +in the long-running code path. The sleep call will trigger a context switch +if there are pending threads, and using an argument of 0 will avoid introducing +delays in the case that there is only a single green thread:: + + from eventlet import greenthread + ... + greenthread.sleep(0) + + +MySQL access and eventlet +------------------------- +Queries to the MySQL database will block the main thread of a service. This is +because OpenStack services use an external C library for accessing the MySQL +database. Since eventlet cannot use monkey-patching to intercept blocking +calls in a C library, the resulting database query blocks the thread. + +The Diablo release contained a thread-pooling implementation that did not +block, but this implementation resulted in a `bug`_ and was removed. + +See this `mailing list thread`_ for a discussion of this issue, including +a discussion of the `impact on performance`_. + +.. _bug: https://bugs.launchpad.net/nova/+bug/838581 +.. _mailing list thread: https://lists.launchpad.net/openstack/msg08118.html +.. _impact on performance: https://lists.launchpad.net/openstack/msg08217.html