GS2-JobQueue

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” in the queue, and executed later either at the timing when the player accesses the server or by an explicit API call.

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, jobs queued for a user are automatically executed at the end of each microservice’s API processing. Jobs queued on the server side are consumed sequentially just by the player operating the app.

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 the GS2-Script exit code, execution log, and result payload, allowing you to review the execution history later.

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;

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

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

Detailed Reference