Locking Strategy

Quick summary

  • Default: LOCAL (in-JVM locking). No extra setup required.
  • REDIS is optional and recommended only for multi-server setups that need cross-instance synchronization.

Config keys

  • locking-strategy (in the main config.yml)
    • Type: string
    • Allowed values: LOCAL, REDIS, BUNGEECORD
    • Default: LOCAL
  • locking section (in config.yml, added in v3.1.0):
locking:
  ttl-ms: 10000       # Lock expiry time in milliseconds
  retry-ms: 50         # Delay between lock acquisition retries
  max-attempts: 20     # Maximum retry attempts before giving up

These timing values apply to all lock strategies and replace the previously hardcoded defaults.

When to use which

  • LOCAL: Single server or small networks where each server handles its own state. Easiest to run and troubleshoot.
  • REDIS: Multiple servers sharing the same economy state. Requires the ezeconomy-redis extension and a configured redis.yml.
  • BUNGEECORD: Proxy-backed locking via plugin messaging. Requires ezeconomy-bungeecord-proxy on the proxy. Single-authority model, not suitable for multi-proxy clusters.

Behavior & safety

  • If REDIS is selected but Redis cannot be initialized, fallback-to-local in redis.yml controls whether the plugin falls back to local locking or disables Redis locking on startup.
  • Transfer operations acquire locks in a deterministic UUID order to avoid cross-instance deadlocks.
  • Changing this setting requires a plugin restart.

How to enable Redis

  1. Install the optional extension ezeconomy-redis.jar into plugins/EzEconomy/libs/.
  2. Set locking-strategy: REDIS in config.yml.
  3. Configure redis.yml (see docs/redis.md) and restart the server.

See also