GS2-JobQueue

Asynchronous job queue

GS2-JobQueue provides a job queue feature for stacking up processes to be executed asynchronously on the game server.

Game processing includes operations that do not need to return a result immediately, and operations that should progress gradually over time on the server side. Such processing can be registered as a “job” and executed automatically by the server or through an explicit Run API call, according to the namespace settings.

Main use cases

An execution platform for running GS2-Script asynchronously
Splitting long-running processing into smaller steps, registering each step as a job, and processing them sequentially
Issuing and executing transactions in batches on the server side for rewards distributed during login
As a completion notification handler for other microservices, performing follow-up processing asynchronously

graph LR
  Producer["Job producer<br/>(Other microservices / GS2-Script)"] --> Queue["GS2-JobQueue"]
  Queue --> Run["Player calls Run<br/>or auto execution"]
  Run --> Script["GS2-Script"]
  Script -- Success --> Result["Recorded as JobResult"]
  Script -- Failure --> Retry{"Max attempts<br/>reached?"}
  Retry -- No --> Queue
  Retry -- Yes --> DeadLetter["Stored as DeadLetterJob"]

Auto run mode

If enableAutoRun is enabled in the namespace settings, registering a job starts its execution on the server. It does not depend on the player making another API call. The default is false; set this option explicitly when choosing server execution.

If enableAutoRun is disabled, the client must explicitly call the Run API to execute jobs.

Job result

The execution result of a job is recorded as a JobResult per attempt number (tryNumber). A JobResult includes statusCode (the HTTP status of script execution) and result (its response body). It does not contain a separate script execution log.

Notification settings

By configuring runNotification and pushNotification in the namespace settings, you can notify the client via GS2-Gateway when a job has been executed, or when a new job has been queued. You can use this notification as a hook to perform further actions on the client, such as re-fetching the remaining information.

Transaction Actions

GS2-JobQueue is often called as the destination of completion notifications from other microservices, and provides job registration as a transaction action.

Acquire Action: Register a job in the user’s queue

For example, a configuration is possible where GS2-Mission completion rewards push jobs into GS2-JobQueue, and GS2-Script is executed in batches later.

Master Data Management

GS2-JobQueue does not have master data. Its behavior is controlled only by the namespace settings.

Example Implementation

Run jobs in your queue

Called when enableAutoRun is disabled, or when you want to explicitly progress job consumption. Calling Run takes one job from the queue, executes GS2-Script, and returns the result. If IsLastJob is true, it indicates that no more jobs remain to be consumed.

    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.RunAsync(
    );
    var isLastJob = domain.IsLastJob;
    var needRetry = result.NeedRetry;

    const auto Domain = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->Run(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto IsLastJob = Domain->IsLastJob();
    const auto NeedRetry = Future->GetTask().Result()->NeedRetry();

var domain = ez.job_queue.namespace_("namespace-0001").me(game_session)
var async_result = await domain.run()
if async_result.error != null:
    push_error(str(async_result.error))
    return
var is_last_job = domain.is_last_job
var need_retry = async_result.result.need_retry

Get a job execution result

Retrieve the execution result of a specific attempt of a specific job.

    var item = await gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: 1
    ).ModelAsync();

    const auto Domain = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Job(
        "job-0001" // jobName
    )->JobResult(
        1 // tryNumber
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto Result = Future->GetTask().Result();

var domain = ez.job_queue.namespace_(
        "namespace-0001"
    ).me(game_session).job(
        "job-0001"
    ).job_result(
        1 # try_number
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

Get the state of a job

Retrieve the latest state of a job queued in the queue. You can check information such as the current attempt count and the GS2-Script registered with the job.

    var item = await gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).ModelAsync();

    const auto Future = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Job(
        "job-0001" // jobName
    )->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto Result = Future->GetTask().Result();

var domain = ez.job_queue.namespace_(
    "namespace-0001"
).me(game_session).job("job-0001")
var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return
var item = async_result.result