#3226 doc: improve multicall documentation
Merged 2 years ago by tkopecek. Opened 2 years ago by ktdreyer.
ktdreyer/koji doc-multicalls  into  master

@@ -182,80 +182,83 @@ 

  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

Rewrite our multicall documentation to use the active voice, clarify examples, and steer users more strongly towards the newer MultiCallSession class.

Metadata Update from @tkopecek:
- Pull-request tagged with: doc

2 years ago

Commit 77ea6f9 fixes this pull-request

Pull-Request has been merged by tkopecek

2 years ago
Metadata