Distributed Locking

Implement distributed locking in BoxLang applications using Redis to prevent concurrent access issues.

🔒 Overview

In clustered environments, it is often necessary to prevent multiple instances from executing methods at the same time, preventing collisions with data access and modification. The bx:RedisLock component provides distributed locking across all running instances in a cluster using Redis as the coordination mechanism.

The component functions similarly to the standard lock component but uses Redis to coordinate locks across multiple servers, ensuring that only one request can execute the locked code at any given time across the entire cluster.

📋 Component Syntax

<bx:RedisLock
    name="lockName"
    cache="redisCacheName"
    timeout="2"
    expires="60"
    throwOnTimeout="true"
    bypass="false"
>
    <!-- Protected code here -->
</bx:RedisLock>

Script Syntax:

bx:redisLock name="lockName" cache="redisCacheName" timeout=2 expires=60 throwOnTimeout=true bypass=false {
    // Protected code here
}

⚙️ Attributes

Attribute

Type

Required

Default

Description

name

string

✅ Yes

Lock name. Only one request can execute code within a lock with a given name at a time. Cannot be an empty string.

cache

string

✅ Yes

The name of the Redis cache (as defined in application cache settings) to use for the lock

timeout

integer

2

Maximum time in seconds to wait to obtain a lock. Must be >= 0. If lock is not obtained within this time, behavior depends on throwOnTimeout.

expires

integer

60

The length of time in seconds before the lock automatically expires. Must be >= 1. Prevents deadlocks if a process crashes while holding a lock.

throwOnTimeout

boolean

true

If true, throws a runtime exception if lock is not obtained within timeout period. If false, skips the body and continues execution.

bypass

boolean

false

If true, bypasses the lock entirely and executes the body immediately. Useful for development environments.

💡 Usage Examples

Basic Distributed Lock

// Protect critical section across all servers
redisLock name="processOrders" cache="redisCache" timeout=5 expires=30 {
    // Only one server can process orders at a time
    var orders = orderService.getPendingOrders();
    for( var order in orders ) {
        orderService.processOrder( order );
    }
}

Lock with Timeout Handling

// Non-blocking lock - skip if unavailable
redisLock
    name="updateCache"
    cache="redisCache"
    timeout=1
    expires=10
    throwOnTimeout=false
{
    cacheService.rebuildExpensiveCache();
}

// Continue execution whether lock was obtained or not

Development Bypass

// Bypass locking in development
var isDevelopment = application.environment == "development";

redisLock
    name="syncInventory"
    cache="redisCache"
    bypass=isDevelopment
{
    inventoryService.synchronizeWithWarehouse();
}

XML Component Syntax

<bx:RedisLock
    name="dailyReport"
    cache="redisCache"
    timeout="10"
    expires="300"
>
    <bx:set var="reportData" value="#reportService.generateDailyReport()#" />
    <bx:set var="result" value="#emailService.sendReport( reportData )#" />
</bx:RedisLock>

🎯 Common Use Cases

Scheduled Task Coordination

// Ensure scheduled task runs on only one server
component {
    function runScheduledTask() {
        redisLock name="dailyCleanup" cache="redisCache" timeout=0 throwOnTimeout=false {
            // Only executes on one server
            cleanupService.performDailyMaintenance();
        }
    }
}

Cache Warming

// Prevent multiple servers from warming cache simultaneously
redisLock name="warmCache" cache="redisCache" timeout=2 expires=120 throwOnTimeout=false {
    if( !cacheService.isWarmed() ) {
        cacheService.warmCache();
    }
}

Database Migration Coordination

// Ensure database migrations run only once across cluster
redisLock name="dbMigration" cache="redisCache" timeout=30 expires=600 {
    migrationService.runPendingMigrations();
}

Sequential Processing

// Process queue items one at a time across all servers
redisLock name="processQueue" cache="redisCache" timeout=5 expires=60 {
    var item = queue.getNextItem();
    if( !isNull( item ) ) {
        processItem( item );
        queue.markComplete( item );
    }
}

🔧 Configuration Requirements

Cache Setup

The lock requires a configured Redis cache in your application:

component {
    this.name = "MyApp";
    this.sessionManagement = true;

    // Configure Redis cache
    this.cache.redis = {
        provider: "Redis",
        properties: {
            server: "localhost",
            port: 6379
        }
    };
}

Cluster Configuration

For multi-server environments, ensure all servers point to the same Redis instance:

// Production configuration
this.cache.redis = {
    provider: "Redis",
    properties: {
        server: "redis.production.com",
        port: 6379,
        password: getSystemSetting( "REDIS_PASSWORD" ),
        ssl: true
    }
};

⚠️ Best Practices

Lock Naming

Use descriptive, unique lock names
Include context in name: "user_#{userId}_update" instead of "update"
Avoid hardcoded IDs - use dynamic names when locking specific resources

// Good: Specific resource lock
redisLock name="invoice_#invoiceId#_generate" cache="redisCache" {
    generateInvoice( invoiceId );
}

// Bad: Too generic
redisLock name="generate" cache="redisCache" {
    generateInvoice( invoiceId );
}

Timeout Configuration

Set timeout based on expected wait time
Set expires longer than maximum expected execution time
Use throwOnTimeout=false for non-critical operations

// Critical operation - throw if can't acquire
redisLock name="payment" cache="redisCache" timeout=10 expires=30 throwOnTimeout=true {
    processPayment();
}

// Non-critical - skip if unavailable
redisLock name="analytics" cache="redisCache" timeout=1 expires=60 throwOnTimeout=false {
    updateAnalytics();
}

Error Handling

Always handle exceptions within locked code
Keep locked code sections as short as possible
Consider using try/catch inside lock body

redisLock name="criticalUpdate" cache="redisCache" {
    try {
        performCriticalUpdate();
    } catch( any e ) {
        logService.error( "Lock execution failed", e );
        // Lock will be released automatically
        rethrow;
    }
}

Development vs Production

Use bypass attribute for development environments
Set via environment variables or application settings

var isDev = application.environment == "development";

redisLock name="sync" cache="redisCache" bypass=isDev {
    syncService.synchronize();
}

🚨 Troubleshooting

Lock Not Acquired

Symptoms: throwOnTimeout exceptions or body not executing

Solutions:

Increase timeout value
Check if another process is holding the lock too long
Verify Redis connectivity
Check Redis logs for connection issues

Deadlocks

Symptoms: Locks never release, operations hang

Solutions:

Ensure expires is set appropriately
Verify locked code completes normally
Check for infinite loops in locked sections
Monitor Redis for stuck lock keys

Performance Issues

Symptoms: High latency acquiring locks

Solutions:

Reduce lock scope - lock smaller code sections
Increase Redis server resources
Check network latency to Redis
Consider Redis Cluster for high-availability

Cache Not Found

Error: "The specified cache [name] is not a Redis cache"

Solutions:

Verify cache name matches application configuration
Ensure cache provider type is "Redis"
Check cache is properly initialized before use

🔍 Monitoring

Lock Metrics

Monitor these aspects of distributed locking:

Lock acquisition time - time spent waiting for locks
Lock hold duration - time locks are held
Failed acquisitions - locks that timeout
Lock expiration events - automatic releases

Redis Key Inspection

Locks are stored in Redis with specific key patterns. Use Redis CLI to inspect:

# List all lock keys
redis-cli KEYS "*lock*"

# Check lock TTL
redis-cli TTL "lock:lockName"

# View lock details
redis-cli GET "lock:lockName"

PreviousCode Usage NextScope Storage

Last updated 4 days ago

Was this helpful?