API Reference of GS2-Lock SDK for Game Engine

Model

EzMutex

Mutex The mutex provided by GS2 is a type of re-entrant lock.

When acquiring a lock, a transaction ID is specified, and the lock can be acquired again only if the same transaction ID is specified. Since it has a reference counter, the same number of unlock operations are required when releasing it.

	Type	Require	Limitation	Description
mutexId	string	✓	~ 1024 chars	Mutex GRN
propertyId	string	✓	~ 1024 chars	Property ID
transactionId	string	✓	~ 256 chars	Transaction ID from which the lock was acquired

Methods

get

Obtain mutex status

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
propertyId	string	✓	~ 1024 chars	Property ID
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzMutex	Mutex

Implementation Example

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

    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;

    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;
    }

Value change event handling

    var domain = gs2.Lock.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mutex(
        propertyId: "property-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    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;

    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Mutex(
        "property-0001" // propertyId
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Lock::Model::FMutex> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

lock

Obtaining a lock

Locks the resource with the property ID for the number of seconds specified by ttl. The transaction ID must be specified when locking. Acquisition of a lock on the same property ID by a different transaction ID will fail. If the lock acquisition request is from the same transaction, the reference count is increased.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
propertyId	string	✓	~ 1024 chars	Property ID
accessToken	string	✓	~ 128 chars	User Id
transactionId	string	✓	~ 256 chars	Transaction ID from which the lock was acquired
ttl	long	✓	~ 9223372036854775805	Duration of lock acquisition (seconds)

Result

	Type	Description
item	EzMutex	Mutex

Implementation Example

    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();

    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;

    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

Releasing a lock

The lock must be released from the same transaction ID. If the lock is re-entered when the lock is acquired, the lock is released the same number of times, and the actual release occurs when the reference count reaches zero.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
propertyId	string	✓	~ 1024 chars	Property ID
accessToken	string	✓	~ 128 chars	User Id
transactionId	string	✓	~ 256 chars	Transaction ID from which the lock was acquired

Result

	Type	Description
item	EzMutex	Mutex

Implementation Example

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

    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;
    }

    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();