query a matrix, vector, or scalar if GrB_wait will do anything to it

[DrTimothyAldenDavis]

RedisGraph requires a method to query a matrix, vector, or scalar to see if it has any pending operations. That is, it returns true

Roi (@swilly22) has one solution: https://github.com/DrTimothyAldenDavis/GraphBLAS/pull/172 . This proposed method has signature (for the GrB_Matrix case):

GrB_Info GxB_Matrix_pending (GrB_Matrix A, bool *has_pending_operations) ;

An alternative would be to include this query in GrB_get, as the _Generic signature:

GrB_Info GrB_get (GrB_Matrix A, GrB_Something whatever, bool *has_pending_operations) ;

where "whatever" would be an enum value like "GrB_PENDING" or "GrB_WILL_WAIT" or whatever.

Any thoughts? Can you consider this for the v2.1 C API?

[BenBrock]

I think adding this functionality is a good idea. As I understand, what you're essentially asking is whether the function call GrB_Wait(A, GrB_COMPLETE) would return immediately?

Given the API already includes the term "complete" for this, you might also consider GrB_Is_complete or GrB_Is_ready as names.

Another bit of prior art to consider is the syntax used by futures, including C++'s std::future. std::future has wait and wait_for, which waits for a certain period of time. Many other C++ future implementations, including my BCL implementations, have is_ready() or check() methods that immediately return a boolean value.

[tgmattso]

I want an API that minimizes cognitive load on our users. Hence, something closely aligned with what we have already make sense.

We already have GrB_wait(A, GrB_COMPLETE). This returns once A is in the state GrB_COMPLETE). I suggest a perturbation of that:

 GrB_test_wait(A, GrB_COMPLETE)

This function always returns immediately. The return value will tell you if its COMPLETE or not. This name is easier for a programmer working with GraphBLAS to remember since it’s a slight perturbation from an existing function.

--Tim

[DrTimothyAldenDavis]

GrB_MATERIALIZE, you mean? That's what I want to test. I want to query in O(1) time without any change to the matrix A if GrB_wait (A, GrB_MATERIALIZE) would do anything to the matrix A.

GrB_wait (A, GrB_COMPLETE) only means "A is ready to pass to another thread". It doesn't mean that A contains no pending work. Thread 1 can pass a matrix to thread 2, and safely leave work in the matrix A for thread 2 to do. That's what GrB_wait (A, GrB_COMPLETE), means, if thread 1 does it.

Currently, my GrB_wait (A, GrB_COMPLETE) only does one thing: #pragma omp flush. Nothing else.

I don't need a GrB_test_wait (A, GrB_COMPLETE), but I suppose that's useful. Better would be the syntax:

GrB_Info GrB_test_wait (GrB_Matrix A, GrB_WaitMode mode, bool &result) ; and result would be true if GrB_wait (A, mode) would do nothing, or false if GrB_wait (A,mode) has work to do.

If there were a GrB_test_wait (A, GrB_COMPLETE, &result), then I guess I would have to keep track of whether or not #pragma omp flush has been on on the thread that wrote to the matrix? Seems awkward. I don't keep that state inside matrix.