From 6ca387f2759fe974214c4ffecf4f0e3d7325ec20 Mon Sep 17 00:00:00 2001 From: John Spray Date: Mon, 9 Jul 2018 12:55:20 -0400 Subject: [PATCH] doc: update mgr plugin page for remote calls Signed-off-by: John Spray --- doc/mgr/plugins.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/mgr/plugins.rst b/doc/mgr/plugins.rst index 8e67819e010..3ceb15be19b 100644 --- a/doc/mgr/plugins.rst +++ b/doc/mgr/plugins.rst @@ -254,6 +254,30 @@ in the Ceph source code for the full list of methods. For an example of how to use this interface, look at the source code of the ``dashboard`` module. +Communicating between modules +----------------------------- + +Modules can invoke member functions of other modules. + +.. automethod:: MgrModule.remote + +Be sure to handle ``ImportError`` to deal with the case that the desired +module is not enabled. + +If the remote method raises a python exception, this will be converted +to a RuntimeError on the calling side, where the message string describes +the exception that was originally thrown. If your logic intends +to handle certain errors cleanly, it is better to modify the remote method +to return an error value instead of raising an exception. + +At time of writing, inter-module calls are implemented without +copies or serialization, so when you return a python object, you're +returning a reference to that object to the calling module. It +is recommend *not* to rely on this reference passing, as in future the +implementation may change to serialize arguments and return +values. + + Logging ------- -- 2.39.5