[concurrency-interest] ManagedBlocker.block() documentation

[Roman Leventov]

Currently, ManagedBlocker's documentation doesn't clarify whether the
execution framework could call block() more than once or not. The
specification for the return value of block() method:

> true if no additional blocking is necessary (i.e., if isReleasable would
return true)

Implies that isReleasable result should change if block() returns true.

It means that to code one-off blocking ops with ManagedBlocker, strictly
against the spec, one must make block() idempotent:

class MyBlocker implements ManagedBlocker {
  boolean done = false;
  boolean block() {
    if (done) return true;
    doMyOneOffBlockingOp();
    done = true;
    return true;
  }
  boolean isReleasable() { return done; }
}

Which is 1) boilerplate 2) non-trivial conclusion, implicit in the doc (so
few people would probably do this; e. g. there is an SO answer from a very
reputable folk that ditch this complexity and call it an "official
solution": https://stackoverflow.com/a/46073118/648955)

So, perhaps, it would make sense to extend the documentation
of ManagedBlocker with reservations about one-off blocking operations, e.
g. like this:

@return true if no additional blocking is necessary (i.e., if isReleasable
would return true, or if block() is a one-off operation)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cs.oswego.edu/pipermail/concurrency-interest/attachments/20191030/702ba732/attachment.html>