single-instance
stableEnforce single-instance application behaviour using lock files, and pass messages between a running instance and new launch attempts.
use plugin single-instance::{try_lock, release_lock, is_running, …} Functions (9)
- try_lock Acquire the single-instance lock for an app
- release_lock Release the lock when the app exits
- is_running Check if another instance holds the lock
- lock_file_path Get the path of the lock file
- instance_id Read the PID stored in the lock file
- current_pid Get the current process PID
- send_message Send a message to the running instance
- read_messages Read and consume pending messages
- clear_messages Discard all pending messages
Acquire the single-instance lock for an app
Attempts to acquire the single-instance lock for app_name. Returns true if the lock was acquired (this is the first instance), or false if another instance is already running. The lock file is written to the system temp directory as zolo-<app_name>.lock.
use plugin single-instance::{try_lock, release_lock}
if try_lock("myapp") {
print("running as primary instance")
// ... do work ...
release_lock("myapp")
} else {
print("another instance is already running")
}
Release the lock when the app exits
Removes the lock file for app_name. Call this when the application exits cleanly to allow the next launch to become the primary instance.
use plugin single-instance::{try_lock, release_lock}
if try_lock("myapp") {
// ... application logic ...
release_lock("myapp")
}
Check if another instance holds the lock
Returns true if the lock file for app_name exists. Use this to check from a secondary instance whether the primary is still active before sending it a message.
use plugin single-instance::{is_running}
if is_running("myapp") {
print("primary instance is active")
}
Get the path of the lock file
Returns the full path to the lock file used by app_name. Useful for debugging or for monitoring the file externally.
use plugin single-instance::{lock_file_path}
let path = lock_file_path("myapp")
print("lock file at: {path}")
Read the PID stored in the lock file
Returns the PID stored inside the lock file, or nil if no lock exists. This is the PID of the running primary instance.
use plugin single-instance::{instance_id}
let pid = instance_id("myapp")
if pid != nil {
print("primary instance PID: {pid}")
}
Get the current process PID
Returns the PID of the current process.
use plugin single-instance::{current_pid}
print("my PID: {current_pid()}")
Send a message to the running instance
Appends message (a string) to the message queue for app_name. A secondary instance calls this to communicate with the primary. Messages are stored in the temp directory as zolo-<app_name>.msg.
use plugin single-instance::{try_lock, send_message}
if try_lock("myapp") {
print("primary instance started")
} else {
send_message("myapp", "open-file:/tmp/doc.txt")
print("sent message to running instance")
}
Read and consume pending messages
Reads and consumes all pending messages for app_name. Returns a table of strings. The message file is deleted after reading so each message is delivered once.
use plugin single-instance::{try_lock, read_messages}
if try_lock("myapp") {
// poll for messages from new launch attempts
let msgs = read_messages("myapp")
for _, msg in msgs {
print("received: {msg}")
}
}
Discard all pending messages
Discards all pending messages for app_name without reading them.
use plugin single-instance::{clear_messages}
clear_messages("myapp")