javadocs and ensuring semaphore release always