The job system

Signal’s job system provides durable, retryable background work that survives process death. Almost all network activity — sending messages, uploading attachments, processing incoming push notifications — runs through it. The core classes live in jobmanager/ and jobs/.

Overview

JobManager
  ├── JobController          orchestrates job execution
  ├── FastJobStorage         in-memory + SQLite job queue
  ├── JobRunner(s)           thread(s) that run jobs
  ├── ConstraintObserver(s)  watch system state (network, battery, …)
  └── Scheduler              wakes the process if the job manager is idle

JobManager is initialized once and accessible via AppDependencies.getJobManager(). All job submission goes through it.

The Job base class

Every job extends Job (or the convenience subclass BaseJob). A job is a durable unit of work described by Job.Parameters:

// jobmanager/Job.java
public abstract class Job {
  // Called to do actual work. Return Result.success(), Result.retry(), or Result.failure().
  public abstract @NonNull Result run();

  // Called when the job will never run again (max attempts exceeded, or fatal failure).
  public abstract void onFailure();

  // Serialize job state so it can be reconstructed after process death.
  public abstract @Nullable byte[] serialize();

  // The factory key used to recreate this job from serialized data.
  public abstract @NonNull String getFactoryKey();
}

BaseJob adds the onRun() / onShouldRetry() pattern and handles the Result dispatch:

// jobs/BaseJob.java
@Override
public @NonNull Result run() {
  try {
    onRun();
    return Result.success(outputData);
  } catch (RuntimeException e) {
    return Result.fatalFailure(e);   // crashes the app
  } catch (Exception e) {
    if (onShouldRetry(e)) {
      return Result.retry(getNextRunAttemptBackoff(getRunAttempt() + 1, e));
    } else {
      return Result.failure();
    }
  }
}

protected abstract void onRun() throws Exception;
protected abstract boolean onShouldRetry(@NonNull Exception e);

Job lifecycle

Submission

The caller creates a job and calls JobManager.add(job) or JobManager.startChain(job).then(nextJob).enqueue(). The job is immediately persisted to FastJobStorage and enqueued.

Constraint check

Before a job runner picks up the job, all declared constraints must be satisfied (e.g., network available). If constraints are not met, the job stays in the queue until a ConstraintObserver fires.

onAdded()

Called on the worker thread as soon as the job enters the queue. Useful for optimistic local state updates (e.g., inserting a pending message into the database).

run()

The job’s main work is executed. Returns Result.success(), Result.retry(backoffMs), or Result.failure().

Success

Result.success() — the job is removed from storage. If there is a chain, the next job becomes eligible.

Retry

Result.retry(backoffMs) — the job remains in storage with an updated nextBackoffInterval. It becomes eligible again after the backoff has elapsed. BaseJob.getNextRunAttemptBackoff() defaults to exponential backoff via BackoffUtil.

Failure

Result.failure() — onFailure() is called. Dependent jobs in the same chain are also failed (cascading failure). The job is removed from storage.

Result types

Result	Meaning
`Result.success()`	Work completed; remove job
`Result.success(outputData)`	Work completed; pass byte[] to the next chained job
`Result.retry(backoffMs)`	Transient failure; retry after the specified delay
`Result.failure()`	Permanent failure; invoke `onFailure()` and fail dependent jobs
`Result.fatalFailure(exception)`	Non-recoverable error; crash the process

Job Parameters

Job.Parameters controls scheduling behavior:

// jobmanager/Job.java (Parameters)
public static final long IMMORTAL     = -1;  // never expires
public static final int  UNLIMITED    = -1;  // no retry limit

private final String       id;
private final long         createTime;
private final long         lifespan;        // how long the job may live before being discarded
private final int          maxAttempts;     // -1 = unlimited
private final String       queue;           // serializes work within a single queue
private final List<String> constraintKeys;  // constraints that must be met before running
private final boolean      memoryOnly;      // if true, job is NOT persisted to SQLite
private final int          globalPriority;  // PRIORITY_HIGH, PRIORITY_DEFAULT, PRIORITY_LOW

Constraints

A Constraint is a condition that must be true before a job can run. All built-in constraints live in jobmanager/impl/:

Constraint	What it checks
`NetworkConstraint`	Any network connectivity
`WifiConstraint`	Wi-Fi connectivity
`NetworkOrCellServiceConstraint`	Network or cell service
`DecryptionsDrainedConstraint`	No pending incoming messages to decrypt
`SealedSenderConstraint`	Sealed sender certificate is available
`SqlCipherMigrationConstraint`	SQLCipher migration has completed
`NotInCallConstraint`	Device is not in an active call
`RegisteredConstraint`	Account is registered with Signal servers
`BatteryNotLowConstraint`	Battery is above a low threshold
`ChargingConstraint`	Device is charging

Each Constraint implementation has a corresponding ConstraintObserver that monitors system state and notifies JobManager when the constraint transitions to met, allowing waiting jobs to be picked up immediately. To declare a constraint on a job:

new Parameters.Builder()
    .addConstraint(NetworkConstraint.KEY)
    .addConstraint(DecryptionsDrainedConstraint.KEY)
    .build()

Job queues and chaining

Jobs in the same queue run serially — a queue acts as a mutual exclusion key. Jobs in different queues (or with no queue) run concurrently up to the configured maxGeneralRunners limit. Chaining ensures that a sequence of jobs runs in order, and that a failure in one job propagates forward:

AppDependencies.getJobManager()
    .startChain(new AttachmentUploadJob(attachmentId))
    .then(new IndividualSendJob(messageId, recipient))
    .enqueue();

Output data from a completed job is passed to the next job(s) in the chain via setOutputData(byte[]) / getInputData().

FastJobStorage

FastJobStorage is the primary JobStorage implementation. It keeps the full job queue in memory for fast access while using JobDatabase (a separate SQLite database from signal.db) for persistence:

// jobs/FastJobStorage.kt
class FastJobStorage(private val jobDatabase: JobDatabase) : JobStorage {

  /** A trimmed version of every job, always in memory. */
  private val minimalJobs: MutableList<MinimalJobSpec> = mutableListOf()

  /** Full JobSpec cache (capped at 1000) for fast getNextEligibleJob. */
  private val jobSpecCache: JobSpecCache = JobSpecCache(JOB_CACHE_LIMIT)

  /** All constraints, cached alongside jobSpecCache. */
  private val constraintsByJobId: LRUCache<String, MutableList<ConstraintSpec>> = LRUCache(JOB_CACHE_LIMIT)

  /** Every dependency, always in memory. */
  private val dependenciesByJobId: MutableMap<String, MutableList<DependencySpec>> = hashMapOf()

  /** Sorted set of jobs eligible for execution right now. */
  private val eligibleJobs: TreeSet<MinimalJobSpec> = TreeSet(EligibleMinJobComparator)

  /** Migration-related jobs, sorted by create time. */
  private val migrationJobs: TreeSet<MinimalJobSpec> = TreeSet(compareBy { it.createTime })
}

JobSpec (the persisted form) captures all scheduling state:

// jobmanager/persistence/JobSpec.kt
data class JobSpec(
  val id: String,
  val factoryKey: String,
  val queueKey: String?,
  val createTime: Long,
  val lastRunAttemptTime: Long,
  val nextBackoffInterval: Long,
  val runAttempt: Int,
  val maxAttempts: Int,
  val lifespan: Long,
  val serializedData: ByteArray?,
  val serializedInputData: ByteArray?,
  val isRunning: Boolean,
  val isMemoryOnly: Boolean,
  val globalPriority: Int,
  val queuePriority: Int,
  val initialDelay: Long
)

Memory-only jobs (isMemoryOnly = true) never touch JobDatabase and are lost on process death. They are suitable for best-effort work that is acceptable to drop.

Key job types

IndividualSendJob

Sends an encrypted message to a single recipient. Usually the second step in a chain after AttachmentUploadJob. Handles retry on network errors and re-encryption on session reset.

GroupSendJob

Sends a message to a group. Fans out to individual sends and manages sender key distribution. Handles the group-send-endorsement flow.

AttachmentUploadJob

Uploads an attachment to Signal’s CDN and records the remote pointer in AttachmentTable. Runs before any send job that requires an attachment.

PushProcessMessageJob

Processes a single decrypted envelope received from the Signal server. Handles message insertion, receipts, group updates, story syncs, and call event processing.

PreKeysSyncJob

Generates new one-time prekeys and/or rotates signed prekeys when the supply on the server is running low. Runs on a DecryptionsDrainedConstraint to avoid racing with message processing.

RefreshAttributesJob

Re-registers the device’s attributes (capabilities, name, profile key) with the Signal server after they change.

Adding a new job

Create the job class

Extend BaseJob in the jobs/ package. Declare a KEY constant for the factory and implement onRun(), onShouldRetry(), onFailure(), and serialize() / deserialize().

public final class MyNewJob extends BaseJob {

  public static final String KEY = "MyNewJob";

  public MyNewJob() {
    this(new Parameters.Builder()
        .addConstraint(NetworkConstraint.KEY)
        .setMaxAttempts(3)
        .setLifespan(TimeUnit.DAYS.toMillis(1))
        .build());
  }

  private MyNewJob(@NonNull Parameters parameters) {
    super(parameters);
  }

  @Override
  protected void onRun() throws Exception {
    // do the work
  }

  @Override
  protected boolean onShouldRetry(@NonNull Exception e) {
    return e instanceof IOException;
  }

  @Override
  public void onFailure() { }

  @Override
  public @Nullable byte[] serialize() { return null; }

  @Override
  public @NonNull String getFactoryKey() { return KEY; }

  public static final class Factory implements Job.Factory<MyNewJob> {
    @Override
    public @NonNull MyNewJob create(@NonNull Parameters parameters, @Nullable byte[] data) {
      return new MyNewJob(parameters);
    }
  }
}

Add an entry for MyNewJob.KEY → new MyNewJob.Factory() in the JobManager.Configuration setup inside AppDependencies (look for the setJobFactories() call).

Submit the job

Call AppDependencies.getJobManager().add(new MyNewJob()) wherever you want to trigger the work.

Never perform network I/O or long-running work directly in onAdded(). That method is called on a queue-management thread. Use it only for fast local state updates.

Development

Internals

Overview

The Job base class

Job lifecycle

Result types

Job Parameters

Constraints

Job queues and chaining

FastJobStorage

Key job types

IndividualSendJob

GroupSendJob

AttachmentUploadJob

PushProcessMessageJob

PreKeysSyncJob

RefreshAttributesJob

Adding a new job

​Overview

​The Job base class

​Job lifecycle

​Result types

​Job Parameters

​Constraints

​Job queues and chaining

​FastJobStorage

​Key job types

IndividualSendJob

GroupSendJob

AttachmentUploadJob

PushProcessMessageJob

PreKeysSyncJob

RefreshAttributesJob

​Adding a new job

Overview

The Job base class

Job lifecycle

Result types

Job Parameters

Constraints

Job queues and chaining

FastJobStorage

Key job types

Adding a new job