GOLF(2gg)

💅 GOLF(2gg) — the lock-file page, bestie edition ✨

okay so welcome to the GOLF(2gg) manual, Development section, and today's main character is lock-file. sit down, grab a strawberry, we're doing process control 🍓

---

🌸 NAME 🌸

lock-file — (files) 🗂️

---

🎀 PURPOSE 🎀

It locks a file exclusively. that's it. that's the whole job. no sharing, no vibes, one winner only 👑

---

✨ SYNTAX ✨

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

look at that optional status clause living its best bracket life 🫶

---

💖 DESCRIPTION 💖

so lock-file tries to create a file at the full path of <file path> — and yeah, if it already existed, it gets deleted first, no hesitation — and then it locks that file exclusively. if it works, literally nobody else can do the same thing unless your current process ends or calls unlock-file. 💀

and the important part: this statement is non-blocking. it does NOT sit there waiting for you. so the move is to check it in a sleepy loop until it succeeds (peep pause-program for that) 🔁

<file path> should be either an existing or a non-existing file with a valid file path. if it exists? deleted. gone. bye. 🙈

<lock id> (the one in the id clause) is a file descriptor associated with the locked file. keep track of it, bestie, you'll need it later.

<status> (the one in the status clause) is the status of the file locking, and here's the whole menu:

• GG_OKAY — successfully locked, slay 🎉
• GG_ERR_FAILED — cannot lock, most likely because another process is already holding a lock 😭
• GG_ERR_INVALID — the path of the file is invalid (i.e. it's empty)
• GG_ERR_CREATE — the lock file cannot be created

---

generally speaking, this statement is for process control. a process uses lock-file to start working on a job that only one process can do at a time; once it's done, it uses the unlock-file statement, and then another process can issue a successful lock-file call. typically you'd issue lock-file inside a sleepy loop (again: pause-program) just waiting for a resource to be released 🧚

⚠️ heads up: a file lock is not carried across children processes. so if your process creates children — like with exec-program — those children have to obtain their own lock. no inheriting, sorry 💀

✨ also: if a process serving a request terminates before the request could issue unlock-file, the lock gets automatically released. the universe cleans up after you 🌈

you can use any file name — probably pick one that actually signifies the purpose of the lock, as long as you have permissions to create it — and you can create any number of them. so basically you can make as many "binary semaphore"-like objects as you want. build your whole little semaphore empire 👑

---

🦋 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
%%

%%

(yeah the second one is just %%. it's giving minimalist. we respect it 🎀)

---

💜 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

---

kisses, bestie 💋 this was $VERSION, dated $DATE, and yes — the footer said $DATE and $VERSION right there next to GOLF(2gg), so now you know the whole lore. go lock something. responsibly. 💅✨