Lock file

18.4.0 released Sep 25, 2023

Lock file

Purpose: Locks file exclusively.

lock-file <file path> id [ define ] <lock id> status [ define ] <status>

lock-file attempts to create a file (deleting all contents of the previous file, if existed), and exclusively lock it. If successful, no other process can do the same unless current process ends or calls unlock-file. This statement is non-blocking, thus you can check in a sleepy loop for success.

<file path> should be either an existing or non-existing file with a valid file path.

<lock id> (in "id" clause) is a file descriptor associated with locked file.

<status> (in "status" clause) represents the status of file locking: VV_OKAY if successfully locked, VV_ERR_FAILED if cannot lock (likely because another process holds a lock), VV_ERR_INVALID if the path of the file is invalid (i.e. if it is empty), VV_ERR_CREATE if lock file cannot be created.

Generally, this statement is used for process control. A process would use lock-file to start working on a job that only one process can do at a time; once done, by using unlock-file statement, another process will be able to issue a successful lock-file call. Typically, lock-file is issued in a sleepy loop, waiting for a resource to be released.

Note that file lock is not carried across children processes (i.e. if your process creates children, such as with exec-program, then such children must obtain their own lock). In addition, if a process serving a request terminates before the request could issue unlock-file, the lock will be automatically released.

You can use any file name (likely choose a name that signifies the purpose of a lock, as long as you have permissions to create it), and create any number of them. This way you can create as many "binary semaphore"-like objects as you like.

Examples

// Get application home directory
get-app directory to define dir

// Create lock file name
write-string define fname
@<<p-out dir>>/.lock
end-write-string

// Enter loop in which something is done, OR, program waits for others to complete their work before doing its own
num lockid;
while (1) {

    // Attempt to lock file
    lock-file fname id lockid status define lockst

    // Check the status of locking
    if (lockst == VV_OKAY) {

        // File successfully locked, simulate working for 20 seconds
        @WORKING
        sleep (20);
        @DONE
        // Exit while loop
        break;

    } else if (lockst == VV_ERR_FAILED) {

        // Another process holds the lock, wait, try again
        sleep(1);
        @WAITING
        continue;

    } else if (lockst == VV_ERR_OPEN || lockst == VV_ERR_INVALID) {

        // Errors
        @BAD LOCK
        return;
    }
}

// Once done, unlock file
unlock-file id lockid
return;