GS2-JobQueue Transaction Actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-JobQueue adds to it.

The transaction actions of GS2-Job Queue address the job queue of one user, identified by the combination of namespace and user. Pushing always creates new jobs, so each push is its own target; deleting addresses one existing job identified by name.

A job pushed by a transaction is treated as not yet existing by the other actions of that transaction, because every action works from the state at the start of the transaction. Split the transaction where you want to push a job and then act on it.

Where you want to push several jobs, listing them in the jobs of one push is simpler and cheaper than specifying the action several times.

Jobs run after the transaction, not inside it

A pushed job is not run as part of the transaction. It is picked up afterwards and run on its own, and what it does is subject to the restrictions of whichever services it touches, not those of this transaction.

This is what makes GS2-Job Queue useful for working around the restrictions of other services. Where two actions cannot go in one transaction because they update the same thing, pushing one of them as a job splits them into separate transactions. In exchange, its result is not yet reflected when the transaction responds, and it no longer succeeds or fails together with the transaction as a whole.

The same idea is available as a setting rather than an explicit action. Turning acquireActionUseJobQueue on for a namespace makes its transactions run their acquire actions one at a time through GS2-Job Queue whenever there are two or more.

Take care with nested transactions

A job deleted from the inside collides with the same job deleted from the outside. Pushing is unaffected, because each push creates its own jobs.

If you want to avoid these restrictions

Pushing jobs is an acquire action and deleting a job is a consume action. A collision between two deletions is between consume actions, so acquireActionUseJobQueue cannot separate them and enableAtomicCommit has to be turned off. Neither setting helps where the concatenated push exceeds the limit and is rejected when the transaction is issued: split the pushes instead.

Concurrency and retries

Pushing does not conflict however many requests overlap, because each push creates its own jobs.

Deleting a job checks that the job still exists, so deleting the same job at the same time makes the one confirmed later fail. The same happens where the job finishes running and is removed while the deletion is in flight.

Consume Action

Gs2JobQueue:DeleteJobByUserId

Delete a job by User ID

Deletes a specific job from the specified user’s job queue. The job is removed regardless of its execution state.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2JobQueue:DeleteJobByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "jobName": "[string]Job Name",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2JobQueue:DeleteJobByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  jobName: "[string]Job Name"
  timeOffsetToken: "[string]Time offset token"

transaction.service("jobQueue").consume.delete_job_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    jobName="[string]Job Name",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2JobQueue:PushByUserId

Register jobs by User ID

Registers one or more jobs to the user’s job queue (up to 10 at a time). Each job specifies a GS2-Script to execute, its arguments, and a maximum retry count. If enableAutoRun is enabled on the Namespace, jobs are executed immediately and asynchronously after registration, and the autoRun flag in the response is set to true. If enableAutoRun is disabled, jobs are queued and must be executed manually via the Run API, with the autoRun flag set to false.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2JobQueue:PushByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "jobs": [
            {
                "scriptId": "[string]Script GRN",
                "args": "[string]Argument",
                "maxTryCount": "[int]Maximum Number of Attempts"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2JobQueue:PushByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  jobs: 
    - scriptId: "[string]Script GRN"
      args: "[string]Argument"
      maxTryCount: "[int]Maximum Number of Attempts"
  timeOffsetToken: "[string]Time offset token"

transaction.service("jobQueue").acquire.push_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    jobs={
        {
            scriptId="[string]Script GRN",
            args="[string]Argument",
            maxTryCount="[int]Maximum Number of Attempts"
        }
    },
    timeOffsetToken="[string]Time offset token",
})