GitHub - bigattichouse/waitlock: Linux commandline tool to provide mutex/semaphore process safety for long running bash/sh operations.

# Install dependencies (Ubuntu/Debian)
sudo apt-get install build-essential autoconf

# Build and install
./configure
make
sudo make install

# Basic usage - acquire exclusive lock (RECOMMENDED)
waitlock myapp || {
    echo "Another instance is already running"
    exit 1
}
# ... do exclusive work ...
# Lock automatically released when script exits

# Execute command with lock (BEST PRACTICE)
waitlock database_backup --exec "/usr/local/bin/backup.sh --daily"

# List active locks
waitlock --list

# Clone the repository
git clone https://github.com/user/waitlock.git
cd waitlock

# Generate configure script (if building from git)
autoreconf -fi

# Configure and build
./configure
make

# Run tests
make check

# Install system-wide
sudo make install

# Or install to custom prefix
./configure --prefix=/usr/local
make install

# Debug build
./configure CFLAGS="-g -O0 -DDEBUG"

# Release build with optimizations
./configure CFLAGS="-O2 -DNDEBUG"

# Cross-compilation example
./configure --host=arm-linux-gnueabihf

# Ubuntu/Debian (when available)
sudo apt-get install waitlock

# CentOS/RHEL (when available)
sudo yum install waitlock

# macOS with Homebrew (when available)
brew install waitlock

waitlock [options] <descriptor>
waitlock --list [--format=<fmt>] [--all|--stale-only]
waitlock --check <descriptor>
echo <descriptor> | waitlock [options]

# Acquire mutex lock (RECOMMENDED APPROACH)
waitlock myapp || {
    echo "Another instance is already running"
    exit 1
}
# ... do exclusive work ...
# Lock automatically released when script exits

# Check if lock is available
if waitlock --check myapp; then
    echo "Lock is available"
else
    echo "Lock is held by another process"
fi

# Execute command while holding lock (BEST PRACTICE)
waitlock backup_job --exec rsync -av /source /destination

# Use with timeout
waitlock --timeout 30 critical_resource || echo "Timeout!"

# ❌ WRONG - Don't do this for script coordination:
waitlock myapp &
# This returns immediately, whether lock was acquired or not
# Both scripts may think they got the lock
# Requires complex PID management and cleanup

# ✅ CORRECT - Use foreground execution:
waitlock myapp || {
    echo "Another instance is already running"
    exit 1
}
# This blocks until lock is acquired or fails
# Clear success/failure indication
# Automatic cleanup when script exits

#!/bin/bash
# Ensure only one backup process runs at a time

waitlock database_backup || {
    echo "Another backup is already running"
    exit 1
}

# Perform backup
mysqldump --all-databases > backup.sql
gzip backup.sql

# Lock automatically released when script exits

#!/bin/bash
# Allow up to 4 concurrent download processes

waitlock --allowMultiple 4 download_pool || {
    echo "Too many downloads already running"
    exit 1
}

# Perform download
wget "https://example.com/file.tar.gz"

# Lock automatically released when script exits

#!/bin/bash
# Use one lock per CPU core, reserving 2 cores for system

waitlock --onePerCPU --excludeCPUs 2 cpu_intensive_task || {
    echo "All CPU slots are busy"
    exit 1
}

# Run CPU-intensive task
./compute_job.sh

#!/bin/bash
# Execute command while holding lock (recommended approach)

waitlock database_backup --exec bash -c "
    mysqldump --all-databases > backup.sql
    gzip backup.sql
    echo 'Backup completed'
"

#!/bin/bash
# Monitor active locks

# List all locks in human-readable format
waitlock --list

# List in CSV format for parsing
waitlock --list --format csv

# Show only stale locks
waitlock --list --stale-only

# Count active locks
waitlock --list --format csv | tail -n +2 | wc -l

#!/bin/bash
# Process files with controlled parallelism

find /data -name "*.csv" | while read file; do
    basename "$file" | waitlock --allowMultiple 3 --exec process_file "$file"
done

# Or with xargs for better performance
find /data -name "*.csv" | \
    xargs -P 10 -I {} sh -c 'waitlock -m 3 batch_processor --exec "process_file {}"'

#!/bin/bash
# Configure via environment variables

export WAITLOCK_TIMEOUT=60
export WAITLOCK_DIR="/var/lock/myapp"
export WAITLOCK_DEBUG=1

waitlock myapp_task --syslog --syslog-facility local0

#!/bin/bash
# Robust error handling

waitlock --timeout 30 critical_resource
case $? in
    0) echo "Lock acquired successfully" ;;
    1) echo "Lock is busy" >&2; exit 1 ;;
    2) echo "Timeout expired" >&2; exit 1 ;;
    3) echo "Usage error" >&2; exit 1 ;;
    *) echo "Unexpected error" >&2; exit 1 ;;
esac

# Your critical section here
perform_critical_operation

#!/bin/bash
# Clean lock release using --done flag (for testing/debugging)

# ⚠️ Note: This is mainly for testing - use --exec for production

# Start long-running process with lock (background for demonstration)
waitlock long_running_task &
LOCK_PID=$!

# Simulate some work
sleep 2

# Later, signal the process to release the lock cleanly
waitlock --done long_running_task

# Wait for the process to exit gracefully
wait $LOCK_PID
echo "Process exited with code: $?"

# ✅ BETTER APPROACH: Use --exec for production
# waitlock long_running_task --exec "./long_running_script.sh"

#!/bin/bash
# Manage GPU resources (RECOMMENDED APPROACH)

# Acquire semaphore slot and run computation
waitlock --allowMultiple 4 gpu_pool || {
    echo "All GPU slots are busy"
    exit 1
}

# Use WAITLOCK_SLOT environment variable for GPU selection
export CUDA_VISIBLE_DEVICES=$WAITLOCK_SLOT
./gpu_computation.py

# Lock automatically released when script exits

# ✅ ALTERNATIVE: Use --exec for cleaner approach
# waitlock --allowMultiple 4 gpu_pool --exec bash -c '
#     export CUDA_VISIBLE_DEVICES=$WAITLOCK_SLOT
#     ./gpu_computation.py
# '

#!/bin/bash
# Coordinate across multiple machines using NFS

export WAITLOCK_DIR="/mnt/shared/locks"

waitlock cluster_job --timeout 300 --exec bash -c "
    echo 'Running on $(hostname)'
    ./distributed_task.sh
"

# Set default timeout
export WAITLOCK_TIMEOUT=300

# Use custom lock directory
export WAITLOCK_DIR="/var/lock/myapp"

# Enable debug output
export WAITLOCK_DEBUG=1

# Prefer specific semaphore slot
export WAITLOCK_SLOT=2

# Log all operations to syslog
waitlock --syslog --syslog-facility local0 myapp

# Monitor syslog for lock operations
tail -f /var/log/syslog | grep waitlock

# Enable debug output
export WAITLOCK_DEBUG=1
waitlock --verbose myapp

# Or use command line
waitlock --verbose myapp

# Clone repository
git clone https://github.com/user/waitlock.git
cd waitlock

# Install development dependencies
sudo apt-get install autoconf automake libtool

# Generate build files
autoreconf -fi

# Configure for development
./configure --enable-debug CFLAGS="-g -O0"

# Build and test
make
make check

# Run internal test suite
./src/waitlock --test

# Run shell-based tests
./test_basic.sh
./test_semaphore.sh
./test_timeout.sh