> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Lock

분산 배타 제어 기능




GS2-Lock 는 리소스 단위로 동작하는 뮤텍스를 제공하여, 여러 서버 프로세스·여러 처리계에서 동일한 리소스에 동시에 접근하는 것을 방지하기 위한 분산 배타 제어 서비스입니다.

게임 운영에서는 "동일한 플레이어에 대해 같은 처리를 이중으로 실행해 버린다", "서로 다른 백엔드 서버가 동일한 데이터를 동시에 덮어써 버린다" 와 같은 문제가 쉽게 발생합니다. GS2-Lock 을 이용하면, 이러한 문제를 마이크로서비스로 제공되는 공유 뮤텍스를 통해 방지할 수 있습니다.

## 뮤텍스의 기본

GS2-Lock 의 잠금은 "네임스페이스", "사용자ID", "프로퍼티 ID" 의 조합으로 식별되는 "뮤텍스" 라는 리소스에 대해 획득합니다.

프로퍼티 ID 에는 배타 제어를 하고 싶은 리소스를 고유하게 식별하는 임의의 문자열을 지정합니다. 예를 들어 "가챠 추첨 처리", "아이템 소지 수 갱신", "외부 연동 알림 전송" 등, 이중 실행을 피하고 싶은 처리마다 서로 다른 프로퍼티 ID 를 할당하는 운용을 생각할 수 있습니다.

```mermaid
graph TD
  Server1["백엔드 서버A"] -->|Lock| Mutex["GS2-Lock<br/>뮤텍스"]
  Server2["백엔드 서버B"] -->|Lock 대기| Mutex
  Mutex -->|획득 성공| Server1
  Server1 -->|Unlock| Mutex
  Mutex -->|획득 성공| Server2
```

### 트랜잭션 ID

잠금을 획득할 때는 트랜잭션 ID 를 지정합니다. 동일한 트랜잭션 ID 로 같은 뮤텍스에 대해 재귀적으로 잠금을 획득한 경우, 참조 카운트가 증가하는 재진입 락(reentrant lock)으로 동작합니다. 해제할 때는 동일한 횟수만큼 Unlock 을 실행함으로써 잠금이 완전히 해제됩니다.

서로 다른 트랜잭션 ID 에 의한 이중 획득은 경합 상태가 되며, 먼저 획득한 세션이 잠금을 해제할 때까지 대기 상태가 됩니다.

### TTL에 의한 자동 해제

잠금에는 TTL(Time To Live)을 설정할 수 있으며, TTL이 경과하면 잠금은 자동으로 해제됩니다.

이를 통해, 잠금을 획득한 처리계가 비정상 종료되거나 네트워크 장애로 잠금 해제 처리가 호출되지 않은 경우에도 데드락을 방지할 수 있습니다. TTL은 처리의 최대 예상 실행 시간에 맞춰 적절한 값을 설정해 주세요.

## 멀티 타이틀·여러 백엔드 간의 배타 제어

GS2-Lock 는 GS2의 마이크로서비스로 제공되기 때문에, 멀티 타이틀 간이나 여러 백엔드 서버, 여러 리전 간에 공통된 배타 제어를 실현할 수 있습니다.

GS2-Script 에서 호출함으로써, 서버 사이드 스크립트 내부에서 다른 스크립트 실행이나 외부 처리와의 배타 제어를 수행하는 것도 가능합니다.

## 트랜잭션 액션

GS2-Lock 에서는 트랜잭션 액션을 제공하지 않습니다.

## 마스터 데이터 관리

GS2-Lock 에서는 마스터 데이터 등록이 없습니다. 네임스페이스를 생성하는 것만으로 이용을 시작할 수 있습니다.

## 구현 예제

GS2-Lock 는 관리 API/서버 사이드 API 중심의 마이크로서비스입니다. 게임 엔진용 SDK(Unity / Unreal Engine / Godot)에는 전용 Domain 클래스가 제공되지 않습니다.

주로 GS2-Script 내의 서버 사이드 로직이나, 자사의 백엔드 서버에서 이용하는 것을 상정하고 있으므로, 게임 클라이언트에서 직접 호출하는 것이 아니라 다음 중 하나의 수단으로 조작할 것을 권장합니다.

- GS2-Script 에서의 호출(서버 사이드 스크립트를 경유한 배타 제어)
- 각종 언어용 일반 SDK(C# / Go / Python / TypeScript / PHP / Java)를 통한 백엔드 서버에서의 호출
- 매니지먼트 콘솔(동작 확인·운용 시)
- GS2 CLI

각종 SDK의 상세 내용은 해당 레퍼런스 페이지를 참조해 주세요.

## 더 실전적인 정보

### 이중 실행 방지 패턴

온라인 게임에서는 네트워크가 불안정하여 플레이어가 동일한 리퀘스트를 짧은 시간에 여러 번 전송하는 경우가 있습니다. 이러한 리퀘스트를 서버 측에서 그대로 받아들이면, 아이템의 이중 지급 등으로 이어집니다.

트랜잭션 ID를 리퀘스트마다 발급하고, GS2-Lock 에서 짧은 시간의 TTL을 가진 잠금을 획득함으로써, 동일한 트랜잭션 ID에 의한 중복 처리는 참조 카운트로 취급되고, 서로 다른 리퀘스트로 받은 동종 처리는 경합으로 걸러낼 수 있습니다.

### 백엔드 간 정합성 확보

여러 백엔드 서버가 공통 리소스에 쓰기를 수행하는 시나리오에서는, GS2-Lock 으로 리소스 단위의 뮤텍스를 획득한 뒤 읽기·갱신·쓰기를 수행하는 설계가 유효합니다. 프로퍼티 ID에 리소스의 식별자를 포함시킴으로써, 리소스별 세밀한 배타 제어를 실현할 수 있습니다.

## 상세 레퍼런스

[GS2-Lock API 레퍼런스](../../api_reference/lock)