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

# GS2-Lock SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-Lock SDK の モデルの仕様 と API のリファレンス



## モデル

### EzMutex

ミューテックス<br>

GS2 の提供するミューテックスは再入可能ロックの一種です。<br>

ロックを取得する際にはトランザクションIDを指定し、同一トランザクションIDを指定した場合にのみ再度ロックを取得できます。<br>
参照カウンタを持つため、解放するときには同回数のアンロック処理が必要です。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| mutexId | string |  | ※ |  |  ~ 1024文字 | ミューテックスGRN<br>※ サーバーが自動で設定 |
| propertyId | string |  | ✓ |  |  ~ 1024文字 | プロパティID<br>ロック対象のリソースを識別するためのIDで、どのリソースに対するロックであるかを決定します。<br>複数の処理が同一リソースへの排他アクセスを必要とする場合、同じプロパティIDを指定する必要があります。 |
| transactionId | string |  | ✓ |  |  ~ 256文字 | トランザクションID<br>ロックを取得するトランザクションの識別子。この ID は再入可能ロックの実現に使用されます。<br>ロック要求が現在のロック保持者と同じトランザクションIDを指定した場合、ロックは再取得に成功し参照カウンタがインクリメントされます。<br>異なるトランザクションIDでのロック要求は、ロックが保持されている間は拒否されます。 |
| ttlAt | long |  |  | 現在時刻から1時間後の絶対時刻 |  | 有効期限日時<br>UNIX 時間・ミリ秒 |

**関連するメソッド:**
get - ミューテックスの状態を取得
lock - ロックを取得
unlock - ロックを解放


---

## メソッド

### get

ミューテックスの状態を取得

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| propertyId | string |  | ✓|  |  ~ 1024文字 | プロパティID<br>ロック対象のリソースを識別するためのIDで、どのリソースに対するロックであるかを決定します。<br>複数の処理が同一リソースへの排他アクセスを必要とする場合、同じプロパティIDを指定する必要があります。 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMutex](#ezmutex) | ミューテックス|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Mutex(
        "property-0001" // propertyId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Mutex(
        "property-0001" // propertyId
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lock::Model::FMutex> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### lock

ロックを取得<br>

ttl で指定した秒数 `プロパティID` のリソースをロックします。<br>
ロックする際には `トランザクションID` を指定する必要があります。<br>
異なる `トランザクションID` による同一 `プロパティID` に対するロック取得は失敗します。<br>
同一トランザクションからのロック取得リクエストの場合は参照カウンタを増やします。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| propertyId | string |  | ✓|  |  ~ 1024文字 | プロパティID<br>ロック対象のリソースを識別するためのIDで、どのリソースに対するロックであるかを決定します。<br>複数の処理が同一リソースへの排他アクセスを必要とする場合、同じプロパティIDを指定する必要があります。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| transactionId | string |  | ✓|  |  ~ 256文字 | トランザクションID<br>ロックを取得するトランザクションの識別子。この ID は再入可能ロックの実現に使用されます。<br>ロック要求が現在のロック保持者と同じトランザクションIDを指定した場合、ロックは再取得に成功し参照カウンタがインクリメントされます。<br>異なるトランザクションIDでのロック要求は、ロックが保持されている間は拒否されます。 |
| ttl | long |  | ✓|  | 0 ~ 9223372036854775805 | ロックを取得する期間（秒） |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMutex](#ezmutex) | ミューテックス|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var result = await domain.LockAsync(
        transactionId: "transaction-0001",
        ttl: 100000L
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var future = domain.LockFuture(
        transactionId: "transaction-0001",
        ttl: 100000L
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Mutex(
        "property-0001" // propertyId
    );
    const auto Future = Domain->Lock(
        "transaction-0001", // transactionId
        100000L // ttl
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```


---

### unlock

ロックを解放<br>

ロックの解放には同一 `トランザクションID` から解放する必要があります。<br>
ロックの取得時に再入を行った場合は同一回数ロックの解放を行い、参照カウンタが0になったタイミングで実際に解放が行われます。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| propertyId | string |  | ✓|  |  ~ 1024文字 | プロパティID<br>ロック対象のリソースを識別するためのIDで、どのリソースに対するロックであるかを決定します。<br>複数の処理が同一リソースへの排他アクセスを必要とする場合、同じプロパティIDを指定する必要があります。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| transactionId | string |  | ✓|  |  ~ 256文字 | トランザクションID<br>ロックを取得するトランザクションの識別子。この ID は再入可能ロックの実現に使用されます。<br>ロック要求が現在のロック保持者と同じトランザクションIDを指定した場合、ロックは再取得に成功し参照カウンタがインクリメントされます。<br>異なるトランザクションIDでのロック要求は、ロックが保持されている間は拒否されます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMutex](#ezmutex) | ミューテックス|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var result = await domain.UnlockAsync(
        transactionId: "transaction-0001"
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    var future = domain.UnlockFuture(
        transactionId: "transaction-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Mutex(
        "property-0001" // propertyId
    );
    const auto Future = Domain->Unlock(
        "transaction-0001" // transactionId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

```


---