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;

See also
Files
close-file  
copy-file  
delete-file  
file-position  
file-storage  
file-uploading  
lock-file  
open-file  
read-file  
read-line  
rename-file  
stat-file  
temporary-file  
uniq-file  
unlock-file  
write-file    
See all
documentation


You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a link back to this page (dofollow) - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind.