diff --git a/specs/train/rabbitmq-driver-threads.rst b/specs/train/rabbitmq-driver-threads.rst new file mode 100644 index 0000000..d4f4cb1 --- /dev/null +++ b/specs/train/rabbitmq-driver-threads.rst @@ -0,0 +1,151 @@ +============================================================================== +Allow customer to choose to use std threads or greenthreads in rabbitmq driver +============================================================================== + +https://blueprints.launchpad.net/oslo.messaging/+spec/rabbitmq-driver-threads + +oslo.messaging RabbitMq driver use greenthreads from eventlet. In some use case +it can be useful to also can use python standard threads. This allow customers +design that they need exactly in their context. This specification proposes +changes to adapt the rabbitmq driver to provide mechanismes needed to lets +customers choice between eventlet greenthreads or python standard threads. + +Problem description +=================== + +The rabbitmq driver is commonly used to healt check the AMQP connections with +rabbitmq to ensure connections by using the driver heartbeat mechanism. + +The AMQP heartbeat can be used in mod_wsgi. the threading library is +monkey_patched by eventlet, and it's not compatible with mod_wsgi. + +Indeed, mod_wsgi stops the execution of its embedded interpreter, the +AMQP heartbeat thread can't be resumed until there's a message to be +processed in the mod_wsgi queue, which would resume the python +interpreter and make eventlet resume the thread. + +Allow customers to use standard threads and disabling eventlet will fix +this kind of issues. + +Proposed change +=============== + +The spec proposes to introduce a new configuration option who lets customers +choose the threading mode to use. By default we'll keep the eventlet mode +with the monkey patched threading module, and user by using configuration +will can choose to turn off the eventlet mode and to use the non monkey +patched mode. + +The ``eventlet_mode`` config option will be introduced, with the default value +defined to turned on (``on``). + +User can choose to set this value to ``off`` to turn off the eventlet mode +and using python standard threads. + +This option will have a default value so doesn't need to update existing +usages. Also the existing usages of this driver will continue to have the +same behaviors if nobody changes the configuration explicitely so it's +transparent for end users. + +Here is a example that describes the introduced option turned off:: + + [oslo_messaging_rabbit] + eventlet_mode = off + + +Alternatives +------------ + +Remove eventlet on the rabbitmq driver and prefer to use possible alternatives +like using futurist. + +Impact on Existing usages +------------------------- + +No impact on the existing usages since the default behavior will continue +to use eventlet by default (``eventlet_mode=on``). + +Security impact +--------------- + +There's a slim chance that driver behavior could change if pre-existing +environment variables are present that happen to match the new option +name described here. + +Performance Impact +------------------ + +No significant performance impact is expected. + +Configuration Impact +-------------------- + +A new option will be added that can impact users in some unidentified +scenarios. + +Developer Impact +---------------- + +Developers will have an additional customization option available. + +Testing Impact +-------------- + +Additional unit tests will be required to cover the added functionality. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + hberaud + +Other contributors: + volunteers? + +Milestones +---------- + +..TODO(hberaud): figure this out + +Work Items +---------- + +* Implement the described modes in rabbitmq driver. +* Update documentation. +* Update the sample configuration generator to include the variable names. +* Update the documentation generator to include the variable names. + + +Incubation +========== + +N/A + +Documentation Impact +==================== + +The documentation will need to be updated to indicate the option can be +overridden with an environment variable and to describe how the described +modes works. + +Dependencies +============ + +N/A + +References +========== + +* Eventlet Best Practices: + `https://review.opendev.org/#/c/154642/`_ +* Related discussion on the ML about mod_wsgi and monkey patch: + `http://lists.openstack.org/pipermail/openstack-discuss/2019-April/005305.html`_ + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode