GS2-Lock SDK for Game Engine API Reference

Specifications of models and API references for GS2-Lock SDK for Game Engine

Models

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	Required	Default	Value Limits	Description
mutexId	string	*		~ 1024 chars	Mutex GRN * Set automatically by the server
propertyId	string	✓		~ 1024 chars	Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID.
transactionId	string	✓		~ 256 chars	Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held.
ttlAt	long		The absolute time 1 hour after the current time		Expiration datetime Unix time, milliseconds

Methods

get

Get Mutex status

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
propertyId	string	✓	~ 1024 chars	Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID.
gameSession	GameSession	✓		GameSession

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"
    );
    
    // 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);

    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 triggered when the value stored in the SDK’s local cache changes.

The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with 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 counter is increased.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
propertyId	string	✓	~ 1024 chars	Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID.
gameSession	GameSession	✓		GameSession
transactionId	string	✓	~ 256 chars	Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held.
ttl	long	✓	0 ~ 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 counter reaches zero.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
propertyId	string	✓	~ 1024 chars	Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID.
gameSession	GameSession	✓		GameSession
transactionId	string	✓	~ 256 chars	Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held.

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