timeout locking and better documentation