From 94ea0a490964841fb1c0b88d26906dc4fd7e757d Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Jan 25 2022 17:16:16 +0000 Subject: doc: improve multicall documentation Rewrite our multicall documentation to use the active voice, clarify examples, and steer users more strongly towards the newer MultiCallSession class. --- diff --git a/docs/source/writing_koji_code.rst b/docs/source/writing_koji_code.rst index 9da07fa..c84b5fc 100644 --- a/docs/source/writing_koji_code.rst +++ b/docs/source/writing_koji_code.rst @@ -182,80 +182,83 @@ receives status on a task. That is the return value. Using multicall ~~~~~~~~~~~~~~~ -Koji supports a multicall feature where many calls are passed to the -server wrapped as a single call. This can reduce the overhead when a -large number of related calls need to be made. +Koji supports XML-RPC multicalls. Clients can send multiple calls to a hub in +a single request. This is a faster and more efficient way to make many +related calls, and it reduces overhead on the client and server. The ``ClientSession`` class provides support for this and there are several examples in the existing client code. Some examples in the cli include: ``edit-host``, ``add-pkg``, ``disable-host``, and ``list-hosts``. -There are two ways to use multicall. -The original modal method works within the ``ClientSession`` object and -prevents making other normal calls until the multicall is completed. -The newer method uses a separate ``MultiCallSession`` object and is much -more flexible. - **Using MultiCallSession** -Note: this feature was added in Koji version 1.18. - -A ``MultiCallSession`` object is used to track an individual multicall attached -to a session. -To create one, you can simply call your session's ``multicall`` method. -Once created, the object can be used like a session, but calls are stored -rather than sent immediately. -The stored calls are executed by calling the ``call_all()`` method. +Koji tracks individual muticalls for a session with a ``MultiCallSession`` +object. To create one, call your session's ``multicall()`` method. Use this +object like a session, but it will store calls rather than sending +immediately. To execute the calls, call the ``call_all()`` method. :: + task_ids_to_cancel = [123, 456, 789] m = session.multicall() - for task_id in mylist: + for task_id in task_ids_to_cancel: m.cancelTask(task_id) m.call_all() -This object can also be used as a context manager, so the following is -equivalent: - -:: +Alternatively, you can use this as a context manager. The following is +equivalent:: + task_ids_to_cancel = [123, 456, 789] with session.multicall() as m: - for task_id in mylist: + for task_id in task_ids_to_cancel: m.cancelTask(task_id) -Method calls to a ``MultiCallSession`` object return a ``VirtualCall`` object -that stands in for the result. -Once the multicall is executed, the result of each call can be accessed via -the ``result`` property of the ``VirtualCall`` object. -Accessing the ``result`` property before the call is executed will result in -an error. +When the context manager exits, the client sends the multicall to the hub +(implicitly executing ``call_all()``). -:: +Another example, getting a list of tag names from ids:: with session.multicall() as m: - tags = [m.getTag(tag_id) for tag_id in mylist] + tags = [m.getTag(tag_id) for tag_id in my_tag_ids] for tag in tags: print(tag.result['name']) -There are two parameters affecting the behavior of the multicall. -If the ``strict`` parameter is set to True, the multicall will raise the first -error it encounters, if any. -If the ``batch`` parameter is set to a number greater than zero, the multicall -will spread the calls across multiple multicall batches of at most that number. -These parameters may be passed when the ``MultiCallSession`` is initialized, -or they may be passed to the ``call_all`` method. +Each method you call on a ``MultiCallSession`` object will return a +``VirtualCall`` object that stands in for the result. + +Once you send the multicall and the hub executes it, you can access the result +of each call via the ``result`` property on each ``VirtualCall`` object. (You +must execute the call before accessing the ``.result`` property, or +``VirtualCall`` will raise an exception.) :: +Two parameters affect the behavior of the multicall. + +* If the ``strict`` parameter is set to ``True``, the multicall will raise the + first error it encounters, if any. +* If the ``batch`` parameter is set to a number greater than zero, the + multicall will spread the calls across multiple multicall batches of at most + that number. + +You may pass these parameters to the ``call_all()`` method, or you may pass +them when you initialize ``MultiCallSession``:: + with session.multicall(strict=True, batch=500) as m: builds = [m.getBuild(build_id) for build_id in mylist] -**Using ClientSession.multiCall** +**Deprecated: Using ClientSession.multiCall** + +.. note:: + This section describes the old (modal) way to make multicalls in Koji: set + the ``.multicall`` property to ``True`` and call the ``.multiCall()`` + method on the ``ClientSession`` object. You cannot make other normal calls + until you complete the multicall with ``.multiCall()``. -Note: this approach is still supported, but we highly recommend using -``MultiCallSession`` as described above, unless you need to support Koji -versions prior to 1.18. + Please switch your code to use the newer ``multicall()`` pattern described + above. Only use this older-style code pattern if you must support Koji + versions prior to 1.18. To use the feature, you first set the ``multicall`` attribute of the session to ``True``. Once this is done, the session will not immediately process