NAME

       lock-file -  (files)

PURPOSE

       Locks file exclusively.

SYNTAX

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

DESCRIPTION

       lock-file  attempts  to  create  file  with  the  full  path of <file path> (deleting it 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 (see  pause-
       program).

       <file  path>  should  be  either an existing or non-existing file with a valid file path. If existing, it
       will be deleted.

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

       <status> (in "status" clause) represents the status of file  locking:  GG_OKAY  if  successfully  locked,
       GG_ERR_FAILED if cannot lock (likely because another process holds a lock), GG_ERR_INVALID if the path of
       the file is invalid (i.e. if it is empty), GG_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 (see
       pause-program), 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

           %% /locktest public
               // Get application home directory
               get-app directory to dir
               // Create lock file name
               write-string fname
               @<<print-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
               set-number lockid
               start-loop
                   // Attempt to lock file
                   lock-file fname id lockid status lockst
                   // Check the status of locking
                   if-true lockst equal GG_OKAY
                       // File successfully locked, simulate working for 20 seconds
                       @WORKING
                       pause-program 20000
                       @DONE
                       // Exit while loop
                       break-loop
                   else-if lockst equal GG_ERR_FAILED
                       // Another process holds the lock, wait, try again for 1 second
                       pause-program 1000
                       @WAITING
                       continue-loop
                   else-if lockst equal GG_ERR_OPEN or lockst equal GG_ERR_INVALID
                       // Errors
                       @BAD LOCK
                       exit-handler
                   end-if
               end-loop
               // Once done, unlock file
               unlock-file id lockid
           %%

       %%

SEE ALSO

        Files

       change-mode  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

$DATE                                               $VERSION                                           GOLF(2gg)