Lock object refcounting can be used to prevent use of locks after they've been destroyed. In typical callback scenarios we know in advance which locks are used and for those cases we can reference the lock object using lock_ref() as long as we are using it and when we know the lock object will not be used any more we call lock_unref(). Before a lock object destroyed the various lock implementations can call lock_unref_and_wait() to ensure no refs are held in a blocking, but not sleeping fashion. The purpose of this API is to eliminate typical drain calls for callback worker threads. Example with callout API:
Before:
mtx_lock(a)
callout_stop(c)
mtx_unlock(a)
callout_drain(c)
mtx_destroy(a)
free(a)
After:
mtx_lock(a)
callout_stop(c)
mtx_unlock(a)
mtx_destroy(a)
free(a)