====== Page locking ======

The page locking mechanism is based around a .lock file that temporarily exists within the dokuwiki/data/locks directory. 

When a page is edited, a .lock file is created by the [[xref>lock()]] function. The name of this file is determined through the ID of the page that is requested to be locked, hashed by MD5. This file is written with, as content, the USER_NAME or the client IP.

The release of a lock is done by deleting the .lock file. This is achieved by the [[xref>unlock()]] function.

Checking for an existing lock is handled by the [[xref>checklock()]] function. This function will also take care of removing stale lock files.

Due to current limitations of the design, the [[xref>lock()]], [[xref>unlock()]] and [[xref>checklock()]] lack proper lock atomicity. [[xref>lock()]] performs lock stealing: it replaces the lock of another process unconditionally.

The typical program flow:

<code php>
if (!checklock($id)) {
    lock($id);
    // work
    unlock($id);
} else {
    // error
}
</code>

avoids lock stealing in the typical case, where the attempts to lock a page are few and far between. However, in a scenario of two concurrent processes, where the [[xref>checklock()]] function is called in the first process, then it is called again in the second process leaves both processes assuming that they are free to lock the page. One of them will inadvertently steal the lock from the other.