> For the complete documentation index, see [llms.txt](/llms.txt)

# 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" 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

```mermaid
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.



**Unity**
```csharp

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

    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.



**Unity**
```csharp

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

    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.



**Unity**
```csharp

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

    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

[GS2-JobQueue API Reference](../../api_reference/job_queue)