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.

TypeRequireDefaultLimitationDescription
mutexIdstring~ 1024 charsMutex GRN
propertyIdstring~ 1024 charsProperty ID
transactionIdstring~ 256 charsTransaction ID from which the lock was acquired

Methods

get

Obtain mutex status

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
propertyIdstring~ 1024 charsProperty ID
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzMutexMutex

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.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->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.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Lock->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->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);

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

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
propertyIdstring~ 1024 charsProperty ID
accessTokenstring~ 128 charsUser Id
transactionIdstring~ 256 charsTransaction ID from which the lock was acquired
ttllong~ 9223372036854775805Duration of lock acquisition (seconds)

Result

TypeDescription
itemEzMutexMutex

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.Model();
    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(
        AccessToken
    )->Mutex(
        "property-0001" // propertyId
    );
    const auto Future = Domain->Lock(
        "transaction-0001",
        100000L
    );
    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 false;
    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

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
propertyIdstring~ 1024 charsProperty ID
accessTokenstring~ 128 charsUser Id
transactionIdstring~ 256 charsTransaction ID from which the lock was acquired

Result

TypeDescription
itemEzMutexMutex

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(
        AccessToken
    )->Mutex(
        "property-0001" // propertyId
    );
    const auto Future = Domain->Unlock(
        "transaction-0001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }