From: James Braza Date: Wed, 21 Feb 2024 19:52:14 +0000 (-0500) Subject: Documenting multiprocessing and events (#10831) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e1e95a6a34ce201840a22c73b7f7dce358fe71d1;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Documenting multiprocessing and events (#10831) * Added documentation on multiprocessing support for event system * Incorporating zzzeek's PR comments into docs as tip section * Removed tip and changed section title to 'Events and Multiprocessing' * Adopting zzzeek's PR comment suggestions * Tweaked wording to be more concise --- diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst index 427da8fb15..e07329f4e7 100644 --- a/doc/build/core/event.rst +++ b/doc/build/core/event.rst @@ -140,6 +140,33 @@ this value can be supported:: # it to use the return value listen(UserContact.phone, "set", validate_phone, retval=True) +Events and Multiprocessing +-------------------------- + +SQLAlchemy's event hooks are implemented with Python functions and objects, +so events propagate via Python function calls. +Python multiprocessing follows the +same way we think about OS multiprocessing, +such as a parent process forking a child process, +thus we can describe the SQLAlchemy event system's behavior using the same model. + +Event hooks registered in a parent process +will be present in new child processes +that are forked from that parent after the hooks have been registered, +since the child process starts with +a copy of all existing Python structures from the parent when spawned. +Child processes that already exist before the hooks are registered +will not receive those new event hooks, +as changes made to Python structures in a parent process +do not propagate to child processes. + +For the events themselves, these are Python function calls, +which do not have any ability to propagate between processes. +SQLAlchemy's event system does not implement any inter-process communication. +It is possible to implement event hooks +that use Python inter-process messaging within them, +however this would need to be implemented by the user. + Event Reference ---------------