Lock files for single instance in Bash Scripting - Deep Dive

Overview - Lock files for single instance

What is it?

Lock files are special files used in scripting to ensure that only one instance of a script or program runs at a time. They act like a 'reserved seat' sign, preventing other copies from starting while one is already running. This avoids conflicts or errors caused by multiple instances working on the same resources simultaneously. Lock files are simple but powerful tools for managing script execution safely.

Why it matters

Without lock files, multiple copies of a script could run at the same time, causing problems like data corruption, duplicated work, or system overload. For example, if two scripts try to update the same file simultaneously, the file could become broken or inconsistent. Lock files prevent these issues by making sure only one script runs at once, keeping systems stable and reliable.

Where it fits

Before learning lock files, you should understand basic shell scripting and how scripts run on a system. After mastering lock files, you can explore more advanced process control techniques like semaphores, job scheduling, or systemd services for managing script execution.

Mental Model

Core Idea

A lock file is a simple marker that signals 'this script is running' so no other instance starts until it finishes.

Think of it like...

It's like putting a 'Do Not Disturb' sign on a hotel room door; it tells others to wait until you're done before entering.

┌───────────────┐
│ Script Start  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Check Lock    │───No───► Start Script
│ File Exists?  │
└──────┬────────┘
       │Yes
       ▼
┌───────────────┐
│ Exit or Wait  │
└───────────────┘

After script finishes:
┌───────────────┐
│ Remove Lock   │
│ File          │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Lock File

Concept: Introduce the idea of a lock file as a simple file that marks a script is running.

A lock file is just a normal file created by a script when it starts. Its presence means 'I'm running now.' When the script finishes, it deletes this file. Other scripts check for this file before starting. If the file exists, they know another instance is running and will not start.

Result

Scripts can detect if another instance is running by checking the lock file's existence.

Understanding that a lock file is just a simple file helps grasp how scripts communicate their running state without complex tools.

2

Foundation

Creating and Removing Lock Files

Concept: Learn how to create and remove lock files safely in a script.

In bash, you create a lock file using commands like 'touch /tmp/myscript.lock'. Before starting work, the script checks if this file exists. If not, it creates it and continues. At the end, it removes the file with 'rm /tmp/myscript.lock'. This ensures the lock only exists while the script runs.

Result

A script that creates a lock file at start and removes it at end, preventing multiple runs.

Knowing how to create and remove lock files is the foundation for controlling script concurrency.

3

Intermediate

Avoiding Race Conditions with Atomic Operations

🤔Before reading on: do you think simply checking if a lock file exists then creating it is always safe? Commit to yes or no.

Concept: Introduce atomic file creation to avoid two scripts creating the lock file simultaneously.

If two scripts check for the lock file at the same time and both see it missing, they might both create it, causing conflicts. To avoid this, use atomic operations like 'ln' (link) or 'mkdir' which either succeed or fail instantly. For example, 'mkdir /tmp/myscript.lockdir' will only succeed for one script. This prevents race conditions.

Result

Only one script can create the lock directory; others fail immediately and know the script is running.

Understanding atomic operations prevents subtle bugs where multiple scripts think they have the lock.

4

Intermediate

Handling Stale Lock Files

🤔Before reading on: do you think a lock file always means a script is currently running? Commit to yes or no.

Concept: Learn how to detect and handle lock files left behind by crashed or killed scripts.

Sometimes a script crashes and never removes the lock file. This 'stale' lock blocks new runs forever. To handle this, scripts can store their process ID (PID) inside the lock file. Before starting, the script reads the PID and checks if that process is still running. If not, it removes the stale lock and proceeds.

Result

Scripts avoid being blocked by stale locks and can recover from crashes safely.

Knowing how to detect stale locks makes scripts more robust and reliable in real-world use.

5

Intermediate

Using flock for Simpler Locking

Concept: Introduce the 'flock' command as a simpler way to manage locks without manual files.

'flock' is a Linux command that manages locks on files automatically. You run your script with 'flock /tmp/myscript.lock -c "your_command"'. It blocks if another instance holds the lock and runs your command only when safe. This avoids manual lock file handling and race conditions.

Result

Scripts can use 'flock' to ensure single instance execution with less code and fewer errors.

Knowing about 'flock' helps write cleaner scripts and avoid reinventing locking logic.

6

Advanced

Lock Files in Distributed Systems

🤔Before reading on: do you think local lock files work the same on multiple machines? Commit to yes or no.

Concept: Explore the challenges of using lock files when scripts run on different machines sharing storage.

In distributed systems, scripts on different machines may share a network file system. Lock files here can cause problems due to delays or caching. Special distributed locking tools or protocols like 'etcd' or 'Zookeeper' are used instead. Simple lock files may not guarantee single instance across machines.

Result

Learners understand the limits of lock files and when to use advanced distributed locking.

Recognizing the limits of lock files prevents false confidence in multi-machine environments.

7

Expert

Race Conditions in Lock Removal and Recovery

🤔Before reading on: do you think removing stale locks is always safe without causing conflicts? Commit to yes or no.

Concept: Understand subtle race conditions when multiple scripts try to remove or recreate locks simultaneously.

When detecting stale locks, two scripts might both decide to remove the lock and start running. This can cause multiple instances despite locking. To avoid this, scripts must re-check the lock after removal or use atomic operations for lock creation. Also, signals and traps can help clean locks on script exit.

Result

Scripts handle edge cases safely, preventing rare but critical concurrency bugs.

Knowing these subtle race conditions is key to building bulletproof locking in production.

Under the Hood

Lock files work by creating a file that signals a script is running. The operating system manages file creation and deletion. Atomic operations like 'mkdir' or 'ln' ensure only one script can create the lock at a time. Scripts check for the lock file's existence before running. If the lock exists, they wait or exit. When the script finishes, it deletes the lock file, releasing the lock. The OS file system guarantees atomicity of these operations, preventing simultaneous creation.

Why designed this way?

Lock files were designed as a simple, universal way to coordinate scripts without complex inter-process communication. Early systems lacked advanced locking tools, so using files was a practical solution. Atomic file system operations provide a reliable way to avoid race conditions. Alternatives like semaphores or message queues are more complex and not always available in shell scripting environments.

┌───────────────┐
│ Script Start  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Atomic Lock   │
│ Creation     │
└──────┬────────┘
       │Success
       ▼
┌───────────────┐
│ Script Runs   │
│ with Lock     │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Lock Removed  │
│ on Exit       │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does the presence of a lock file always mean the script is running? Commit to yes or no.

Common Belief: If a lock file exists, the script is definitely running.

Reality: A lock file can be left behind if the script crashes or is killed, causing a stale lock.

Why it matters: Believing this causes scripts to never run again, blocking important tasks indefinitely.

Quick: Is checking for a lock file then creating it separately always safe? Commit to yes or no.

Common Belief: Checking if a lock file exists before creating it is enough to prevent multiple instances.

Reality: This can cause race conditions where two scripts create the lock simultaneously.

Why it matters: Ignoring this leads to multiple script instances running, causing conflicts and errors.

Quick: Can local lock files guarantee single instance across multiple machines? Commit to yes or no.

Common Belief: Lock files on shared network storage work the same as local locks for multiple machines.

Reality: Network delays and caching can cause lock files to be unreliable across machines.

Why it matters: Relying on local lock files in distributed systems can cause multiple instances and data corruption.

Quick: Is removing a stale lock file always safe without extra checks? Commit to yes or no.

Common Belief: Any script can safely remove a stale lock file and start running.

Reality: Multiple scripts might remove the lock simultaneously, causing multiple instances.

Why it matters: This subtle race condition can break the single instance guarantee and cause hard-to-debug errors.

Expert Zone

1

Lock files should be created using atomic operations like 'mkdir' or 'ln' to avoid race conditions, not just 'touch'.

2

Storing the process ID inside the lock file allows scripts to detect if the locking process is still alive, preventing stale locks.

3

Using shell traps to remove lock files on script exit or interruption prevents stale locks caused by unexpected termination.

When NOT to use

Lock files are not suitable for distributed systems where scripts run on multiple machines sharing storage. In such cases, use distributed locking services like etcd, Zookeeper, or Redis locks that handle network delays and consistency.

Production Patterns

In production, scripts often use 'flock' for simple locking or create lock directories atomically. They store PIDs in lock files and use traps to clean up. Monitoring tools watch for stale locks and alert operators. For complex systems, distributed locks or job schedulers ensure single instance execution.

Connections

Mutex in Programming

Lock files are a filesystem-based form of mutex (mutual exclusion) used to prevent concurrent access.

Understanding lock files helps grasp the general concept of mutexes used in programming to avoid conflicts.

Database Transactions

Both lock files and database transactions manage access to shared resources to keep data consistent.

Knowing how lock files work clarifies how databases use locks to prevent conflicting changes.

Traffic Lights in Road Systems

Lock files act like traffic lights controlling when scripts can proceed, preventing crashes like cars colliding.

Seeing lock files as traffic control helps understand the importance of coordination in concurrent systems.

Common Pitfalls

#1 Creating a lock file by checking existence then creating it separately causes race conditions.

Wrong approach:

if [ ! -f /tmp/myscript.lock ]; then
touch /tmp/myscript.lock
fi
# proceed with script

Correct approach:

if mkdir /tmp/myscript.lockdir 2>/dev/null; then
# proceed with script
else
echo "Script already running"
exit 1
fi

Root cause:

The separate check and create steps are not atomic, allowing two scripts to create the lock simultaneously.

#2 Not removing lock files on script exit causes stale locks blocking future runs.

Wrong approach:

touch /tmp/myscript.lock
# script work
# script ends without removing lock

Correct approach:

trap 'rm -rf /tmp/myscript.lockdir' EXIT
mkdir /tmp/myscript.lockdir
# script work
# lock removed automatically on exit

Root cause:

Ignoring cleanup on exit leads to leftover lock files that block new script instances.

#3 Assuming lock files work the same on multiple machines with shared storage.

Wrong approach:

Scripts on different servers create /shared/myscript.lock without extra coordination.

Correct approach:

Use distributed locking tools like etcd or Redis to coordinate locks across machines.

Root cause:

Network file systems have caching and delay issues that break simple lock file assumptions.

Key Takeaways

Lock files are simple files that signal a script is running to prevent multiple instances.

Atomic creation of lock files or directories is essential to avoid race conditions.

Scripts must handle stale lock files by checking if the locking process is still alive.

The 'flock' command offers a simpler and safer way to manage locks in bash scripts.

Lock files have limits in distributed systems where specialized tools are needed.