Curator InterProcessMutex vs InterProcessSemaphoreMutex

Question

What's the difference between InterProcessMutex vs InterProcessSemaphoreMutex? The docs say InterProcessSemaphoreMutex is the same InterProcessMutex except it's not reentrant. But I don't know what reentrant means.

Answer 1

I'm the main author of Apache Curator. Irrespective of what the docs may or may not say I'd like, for the record, to give the exact use cases for each of the two classes.

InterProcessMutex

InterProcessMutex should be used when you need to be able to lock in a re-entrant manner. This means that a given thread is said to "own" the lock once acquired and can lock it again if needed. This is useful if the thread passes the lock object around to other methods that need not be concerned if the lock has been acquired or not. Note that this also means that only the owning thread can release the lock. Here's an example:

InterProcessMutex lock = new InterProcessMutex(...);

if ( !lock.acquire(...) ) ... // if acquire failed: throw, return, etc
try {
   doWork(lock);    // doWork() can safely call lock.acquire() again on the lock
} finally {
    lock.release();
}

Once acquired, if the lock is released in a different thread than the one used to acquire the lock IllegalMonitorStateException is thrown.

InterProcessSemaphoreMutex

InterProcessSemaphoreMutex is a relaxed version of a lock that does not make note of the thread that acquired it. It has simpler semantics. Each InterProcessSemaphoreMutex instance can be acquired exactly once and must be balanced by a release (in any thread). i.e.

InterProcessSemaphoreMutex lock = new InterProcessSemaphoreMutex(...);

lock.acquire();
lock.acquire();    // this will block forever

I hope this helps. If the docs need clarification we'd appreciate a Pull Request with improvements.

Answer 2

In this context, reentrancy means that a thread can call acquire on the same lock more than once and not block when calling it the second or third time. It must balance all acquires with the same number of releases, however. This StackOverflow post talks more about re-entrant locks:

What is the Re-entrant lock and concept in general?

Specific to Curator, here is what the documentation has to say about the different locks:

Shared Re-entrant lock aka InterProcessMutex:

public void acquire()
Acquire the mutex - blocking until it's available. Note: the same thread can call acquire re-entrantly. Each call to acquire must be balanced by a call to release()

Shared lock (non-reentrant) aka InterProcessSemaphoreMutex:

public void acquire()
Acquire the mutex - blocking until it's available. Must be balanced by a call to release().

In the following example, if lock were a reentrant lock, then the code below would run to completion and work normally. If lock were not a reentrant lock, the thread would deadlock while calling the second lock.acquire():

lock.acquire();
lock.acquire();
doWork();
lock.release();
lock.release();

Reentrant locks tend to be a little more costly in implementation, but easier to use.

The above pattern happens frequently when you have multiple public methods into your API that must lock, but your implementation has public methods calling other public methods. You can avoid this by having your public methods do locking and only locking, and then call a private method that assumes it is always executed under the lock; then your private methods can call other private methods without needing to acquire the lock more than once.

Edit to address @Randgalt's comments:

Curator's InterProcessMutex requires that the same thread that acquires the lock release it. InterProcessSemaphoreMutex does not. Maybe you misread what I wrote? Maybe I wasn't clear? Don't know. Anyway, this is the case.

This is patently false; neither lock allows you to release it from a thread other than the thread that acquired the lock. Furthermore, this still has nothing to do with the question of "what is re-entrancy" in this context - and in this context, re-entrancy is whether or not you can call acquire on the same lock more than once on the same thread.

InterProcessMutex.release():

public void release()
Perform one release of the mutex if the calling thread is the same thread that acquired it. If the thread had made multiple calls to acquire, the mutex will still be held when this method returns.

InterProcessSemaphoreMutex.release():

public void release()
Perform one release of the mutex if the calling thread is the same thread that acquired it.

Emphasis added. Neither lock allows you to unlock it from any thread other than the thread that owns the lock - and this makes sense, because both locks are mutexes, and that is one of the properties of a mutex.