doc: filter_functions

Author: d-w-moore

irods/parallel.py

@@ -26,6 +26,9 @@
 
 
 class FILTER_FUNCTIONS:
+    """The members of this class are free functions designed to be passed to
+       the "filter_function" parameter of the abort_parallel_transfers function.
+    """
     foreground = staticmethod(lambda item: isinstance(item[1], tuple))
     background = staticmethod(lambda item: not isinstance(item[1], tuple))
 
@@ -34,22 +37,34 @@ def abort_parallel_transfers(
     dry_run=False, filter_function=None, transform=weakref.WeakKeyDictionary
 ):
     """
-    If no explicit arguments are given, all ongoing parallel puts and gets are cancelled
-    as soon as possible.  The corresponding threads are signalled to exit by calling the
-    quit() method on their corresponding transfer-manager objects.
+    If no explicit arguments are given, all ongoing parallel puts and gets are
+    cancelled as soon as possible.  The corresponding threads are signalled to
+    exit by calling the quit() method on their corresponding transfer-manager
+    objects.
+
+    Setting dry_run=True results in no such cancellation being performed,
+    although a dict object will be computed for the return value containing,
+    as its keys, the transfer-manager objects that would have been so affected.
+
+    filter_function is usually left to its default value of None.  By applying
+    a member of the FILTER_FUNCTIONS class, the caller may specify which
+    transfer-managers are affected and/or reflected in the return value:
 
-    Setting dry_run=True results in no such cancellation being performed, although a dict object
-    will be computed for the return value containing, as its keys, the transfer-manager objects that
-    would have been so affected.
+        FILTER_FUNCTIONS.foreground for example limits its scope to instances
+        of session.data_object.put() and session.data_object.get() that are
+        running synchronously.  These calls block within the thread(s) that
+        are calling them.
 
-    filter_function is usually left to its default value of None.  Otherwise the effect will be to
-    limit which transfers are to be aborted (or simply returned, if dry_run=True).
+        FILTER_FUNCTIONS.background limits its scope to transfers started by
+        calls to io_main() which used Oper.NONBLOCKING to spawn the put or
+        get operation in the background.
 
     transform defaults to a dictionary type with weak keys, since
-    allowing strong references to transfer manager objects may artificially increase lifetimes of
-    threads and other objects unnecessarily and complicate troubleshooting by altering library
-    behavior.  Consider using transform=len if all that is desired is to check how many transfers
-    were cancelled.
+    allowing strong references to transfer-manager objects may artificially
+    increase lifetimes of threads and other objects unnecessarily and
+    complicate troubleshooting by altering library behavior.  Consider using
+    transform=len if all that is desired is to check how many parallel
+    transfers exist in total, at the time.
     """
     mgrs = dict(filter(filter_function, transfer_managers.items()))
     if not dry_run: