Add "complete" option to wait methods (python-graphblas#334)

I don't know how useful this will be in Python, but including for completeness.
I'm not fond of the names "materialize" and "complete", but these are what are in the spec.

graphblas/core/matrix.py

@@ -13,6 +13,7 @@
 from .mask import Mask, StructuralMask, ValueMask
 from .operator import UNKNOWN_OPCLASS, find_opclass, get_semiring, get_typed_op, op_from_string
 from .scalar import (
+    _COMPLETE,
     _MATERIALIZE,
     Scalar,
     ScalarExpression,
@@ -661,17 +662,30 @@ def diag(self, k=0, dtype=None, *, name=None):
                 rv << d[: rv._size]
         return rv
 
-    def wait(self):
-        """Wait for a computation to complete.
+    def wait(self, how="materialize"):
+        """Wait for a computation to complete or establish a "happens-before" relation
+
+        Parameters
+        ----------
+        how : {"materialize", "complete"}
+            "materialize" fully computes an object.
+            "complete" establishes a "happens-before" relation useful with multi-threading.
+            See GraphBLAS documentation for more details.
 
         In `non-blocking mode <../user_guide/init.html#graphblas-modes>`__,
         the computations may be delayed and not yet safe to use by multiple threads.
         Use wait to force completion of the Matrix.
 
         Has no effect in `blocking mode <../user_guide/init.html#graphblas-modes>`__.
         """
-        # TODO: expose COMPLETE or MATERIALIZE options to the user
-        call("GrB_Matrix_wait", [self, _MATERIALIZE])
+        how = how.lower()
+        if how == "materialize":
+            mode = _MATERIALIZE
+        elif how == "complete":
+            mode = _COMPLETE
+        else:
+            raise ValueError(f'`how` argument must be "materialize" or "complete"; got {how!r}')
+        call("GrB_Matrix_wait", [self, mode])
 
     def get(self, row, col, default=None):
         """Get an element at (``row``, ``col``) indices as a Python scalar.

graphblas/core/scalar.py

@@ -448,18 +448,31 @@ def dup(self, dtype=None, *, clear=False, is_cscalar=None, name=None):
                     new_scalar.value = self.value
         return new_scalar
 
-    def wait(self):
-        """Wait for a computation to complete.
+    def wait(self, how="materialize"):
+        """Wait for a computation to complete or establish a "happens-before" relation
+
+        Parameters
+        ----------
+        how : {"materialize", "complete"}
+            "materialize" fully computes an object.
+            "complete" establishes a "happens-before" relation useful with multi-threading.
+            See GraphBLAS documentation for more details.
 
         In `non-blocking mode <../user_guide/init.html#graphblas-modes>`__,
         the computations may be delayed and not yet safe to use by multiple threads.
         Use wait to force completion of the Scalar.
 
         Has no effect in `blocking mode <../user_guide/init.html#graphblas-modes>`__.
         """
-        # TODO: expose COMPLETE or MATERIALIZE options to the user
+        how = how.lower()
+        if how == "materialize":
+            mode = _MATERIALIZE
+        elif how == "complete":
+            mode = _COMPLETE
+        else:
+            raise ValueError(f'`how` argument must be "materialize" or "complete"; got {how!r}')
         if not self._is_cscalar:
-            call("GrB_Scalar_wait", [self, _MATERIALIZE])
+            call("GrB_Scalar_wait", [self, mode])
 
     def get(self, default=None):
         """Get the internal value of the Scalar as a Python scalar.
@@ -770,6 +783,7 @@ def _dict_to_record(np_type, d):
 
 
 _MATERIALIZE = Scalar.from_value(lib.GrB_MATERIALIZE, is_cscalar=True, name="GrB_MATERIALIZE")
+_COMPLETE = Scalar.from_value(lib.GrB_COMPLETE, is_cscalar=True, name="GrB_COMPLETE")
 
 utils._output_types[Scalar] = Scalar
 utils._output_types[ScalarIndexExpr] = Scalar

graphblas/core/vector.py

@@ -12,6 +12,7 @@
 from .mask import Mask, StructuralMask, ValueMask
 from .operator import UNKNOWN_OPCLASS, find_opclass, get_semiring, get_typed_op, op_from_string
 from .scalar import (
+    _COMPLETE,
     _MATERIALIZE,
     Scalar,
     ScalarExpression,
@@ -578,17 +579,30 @@ def diag(self, k=0, *, name=None):
         call("GrB_Matrix_diag", [_Pointer(rv), self, k])
         return rv
 
-    def wait(self):
-        """Wait for a computation to complete.
+    def wait(self, how="materialize"):
+        """Wait for a computation to complete or establish a "happens-before" relation
+
+        Parameters
+        ----------
+        how : {"materialize", "complete"}
+            "materialize" fully computes an object.
+            "complete" establishes a "happens-before" relation useful with multi-threading.
+            See GraphBLAS documentation for more details.
 
         In `non-blocking mode <../user_guide/init.html#graphblas-modes>`__,
         the computations may be delayed and not yet safe to use by multiple threads.
         Use wait to force completion of the Vector.
 
         Has no effect in `blocking mode <../user_guide/init.html#graphblas-modes>`__.
         """
-        # TODO: expose COMPLETE or MATERIALIZE options to the user
-        call("GrB_Vector_wait", [self, _MATERIALIZE])
+        how = how.lower()
+        if how == "materialize":
+            mode = _MATERIALIZE
+        elif how == "complete":
+            mode = _COMPLETE
+        else:
+            raise ValueError(f'`how` argument must be "materialize" or "complete"; got {how!r}')
+        call("GrB_Vector_wait", [self, mode])
 
     def get(self, index, default=None):
         """Get an element at ``index`` as a Python scalar.

graphblas/tests/test_matrix.py

@@ -2570,6 +2570,10 @@ def test_wait(A):
     A2 = A.dup()
     A2.wait()
     assert A2.isequal(A)
+    A2.wait("materialize")
+    A2.wait("complete")
+    with pytest.raises(ValueError):
+        A2.wait("badmode")
 
 
 def test_pickle(A):

graphblas/tests/test_scalar.py

@@ -312,6 +312,10 @@ def test_invert():
 
 def test_wait(s):
     s.wait()
+    s.wait("materialize")
+    s.wait("complete")
+    with pytest.raises(ValueError):
+        s.wait("badmode")
 
 
 @autocompute

graphblas/tests/test_vector.py

@@ -1350,6 +1350,10 @@ def test_wait(v):
     v2 = v.dup()
     v2.wait()
     assert v2.isequal(v)
+    v2.wait("materialize")
+    v2.wait("complete")
+    with pytest.raises(ValueError):
+        v2.wait("badmode")
 
 
 def test_pickle(v):