GS2-Lock
GS2-Lock is a distributed mutual exclusion service that provides a mutex operating on a per-resource basis, preventing multiple server processes and multiple execution environments from accessing the same resource simultaneously.
In game operations, problems such as “performing the same process twice on the same player” or “different backend servers writing to the same data concurrently” can easily occur. GS2-Lock prevents these problems through a shared mutex provided as a microservice.
Mutex basics
GS2-Lock acquires locks on a “mutex” resource identified by a combination of “namespace”, “user ID”, and “property ID”.
For the property ID, you specify an arbitrary string that uniquely identifies the resource you want to mutually exclude. For example, a usage pattern is to assign a different property ID per process you want to avoid double-executing, such as “gacha drawing process”, “item count update”, or “external integration notification”.
graph TD Server1["Backend Server A"] -->|Lock| Mutex["GS2-Lock<br/>Mutex"] Server2["Backend Server B"] -->|Wait for Lock| Mutex Mutex -->|Acquired| Server1 Server1 -->|Unlock| Mutex Mutex -->|Acquired| Server2
Transaction ID
A transaction ID is specified when acquiring a lock. If the same transaction ID acquires a lock on the same mutex recursively, the reference count is incremented and it behaves as a reentrant lock. The lock is fully released only when Unlock is executed the same number of times.
A double acquisition by a different transaction ID becomes a conflict, and the new session waits until the previously holding session releases the lock.
Automatic release by TTL
A TTL (Time To Live) can be set on a lock, and the lock is automatically released after the TTL elapses.
This prevents deadlocks even if the process that acquired the lock abnormally terminates or the lock release call is not made due to a network failure. Set the TTL to an appropriate value based on the maximum expected execution time of the process.
Mutual exclusion across multi-title and multiple backends
Because GS2-Lock is provided as a GS2 microservice, you can implement common mutual exclusion across multiple titles, multiple backend servers, and multiple regions.
You can also call it from GS2-Script to perform mutual exclusion between the internals of server-side scripts and other script executions or external processes.
Transaction Actions
GS2-Lock does not provide transaction actions.
Master Data Management
GS2-Lock does not have master data registration. You can start using it just by creating a namespace.
Example Implementation
GS2-Lock is a microservice centered on management / server-side APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine).
Because it is primarily intended for use within server-side logic in GS2-Script or from your own backend servers, instead of calling it directly from the game client, we recommend operating it via one of the following means.
- Calling from GS2-Script (mutual exclusion through server-side scripts)
- Calling from the backend server using general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java)
- Management console (for verification and operations)
- GS2 CLI
For details on each SDK, see the corresponding reference page.
More practical information
Double-execution prevention pattern
In online games, due to unstable networks, players may send the same request multiple times in a short period. If such requests are accepted on the server side, they can lead to issues such as double item granting.
By issuing a transaction ID per request and acquiring a lock with a short TTL in GS2-Lock, duplicate processing with the same transaction ID is treated as a reference count, while processing of the same kind received as a different request is rejected as a conflict.
Ensuring consistency between backends
In scenarios where multiple backend servers write to a common resource, a design that acquires a per-resource mutex in GS2-Lock and then performs read-modify-write is effective. By embedding the resource identifier in the property ID, you can achieve fine-grained mutual exclusion per resource.