# antirez/disque architecture

> Architecture diagram of the GitHub repository antirez/disque, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antirez/disque
- Repository: https://github.com/antirez/disque

## Overview

##### Project Type and Purpose
- Disque is a distributed, in-memory job queue/message broker written in C.
- It mimics Redis’s non-blocking event-loop server model but adds synchronous replication, multi-master clustering, and at-least-once/at-most-once delivery semantics.
- Purpose: provide a fault-tolerant, self-contained, simple, high-performance job queue across multiple nodes.

##### Key Architectural Elements from File Structure
- Top‐level directories:
- src/ – core server implementation (networking, event loop, job/queue logic, cluster bus)
- deps/ – bundled libraries (hiredis client, jemalloc allocator, linenoise CLI helper)
- tests/ – integration and unit tests for cluster and server behavior
- Build and config: Makefile, disque.conf example, Travis CI setup
- No separate frontend; clients use Redis protocol via hiredis or custom libraries.

##### Main Components
a. Clients (Producers/Consumers)
- Via Redis‐compatible TCP protocol (default port 7711)
- Send ADDJOB, GETJOB, ACKJOB, FASTACK, etc.
b. Disque Nodes
- Event-driven server (`disque-server`)
- Contains modules: networking (ae.*), command parser, job store, queue manager, cluster bus, AOF persistence
c. Cluster Bus (Inter-node Communication)
- Full mesh TCP links (each node ↔ every other node) on port = basePort + 10000
- Exchanges PING/PONG/FAIL for failure detection, REPLJOB/GOTJOB for replication, ENQUEUE/QUEUED/WILLQUEUE for re-queue logic, SETACK/GOTACK/DELJOB for ack propagation and GC, NEEDJOBS/YOURJOBS for federation
d. In-memory Data Structures
- Job objects with state (“wait-repl”, “active”, “queued”, “acked”)
- Queues per topic (sorted by creation time)
- Tables for delivered replicas and ack confirmations
e. Optional Persistence
- AOF file for write-ahead logging of job creation/deletion
- Controlled restart mode for atomic reload of full state

##### Relationships and Data Flow
- Client → Node: commands flow over TCP; node processes commands in event loop
- Node ↔ Node (Cluster Bus):
- Replication messages (REPLJOB → GOTJOB) to satisfy W acknowledgements
- Queue federation (NEEDJOBS → YOURJOBS) when local queue empty but client blocked
- Ack propagation (ACKJOB → SETACK → GOTACK → DELJOB) to garbage‐collect jobs
- Re‐queue timers (WILLQUEUE/QUEUED) for retry semantics
- Node ↔ Disk: AOF writes on ADDJOB/DELJOB, and reload on startup or controlled rewrite

##### Architectural Patterns and Design Principles
- Event-driven, single‐threaded reactor pattern (ae.c/h modules)
- Share-nothing, multi-master cluster: no leader election, symmetric roles
- Full mesh gossip for failure detection (light-weight PING/PONG/FAIL)
- Best-effort, eventually consistent federation for queue federation
- Asynchronous replication with tunable sync parameter (W replicas)
- Timer‐based state machines for re-queue and garbage collection

## Diagram (Mermaid)

```mermaid
graph TB
    classDef clients fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef node fill:#98FB98,stroke:#333,stroke-width:1px
    classDef cluster fill:#FFA500,stroke:#333,stroke-width:1px
    classDef persistence fill:#D3D3D3,stroke:#333,stroke-width:1px

    Clients["Clients\n(Producers/Consumers)"]:::clients
    click Clients "https://github.com/antirez/disque/blob/master/src/disque-cli.c"
    click Clients "https://github.com/antirez/disque/tree/master/deps/hiredis/"

    subgraph "Disque Node A"
        direction TB
        NE_A["Network / Event Loop"]:::node
        ae_c_A["ae.c"]:::node
        ae_h_A["ae.h"]:::node
        ae_epoll_A["ae_epoll.c"]:::node
        ae_kqueue_A["ae_kqueue.c"]:::node
        ae_select_A["ae_select.c"]:::node
        ae_evport_A["ae_evport.c"]:::node
        anet_c_A["anet.c"]:::node
        anet_h_A["anet.h"]:::node
        networking_A["networking.c"]:::node

        CP_A["Command Processor"]:::node
        server_c_A["server.c"]:::node
        server_h_A["server.h"]:::node
        config_c_A["config.c"]:::node
        config_h_A["config.h"]:::node

        JS_A["Job Store & Queues"]:::node
        job_c_A["job.c"]:::node
        job_h_A["job.h"]:::node
        queue_c_A["queue.c"]:::node
        queue_h_A["queue.h"]:::node
        object_c_A["object.c"]:::node
        dict_c_A["dict.c"]:::node
        dict_h_A["dict.h"]:::node

        CB_A["Cluster Bus"]:::cluster
        cluster_c_A["cluster.c"]:::cluster
        cluster_h_A["cluster.h"]:::cluster

        AOF_A["AOF Persistence"]:::persistence
        aof_c_A["aof.c"]:::persistence
        rio_c_A["rio.c"]:::persistence
        rio_h_A["rio.h"]:::persistence
        disque_check_A["disque-check-aof.c"]:::persistence

        UTIL_A["Utility"]:::node
        util_c_A["util.c"]:::node
        util_h_A["util.h"]:::node
        zmalloc_c_A["zmalloc.c"]:::node
        zmalloc_h_A["zmalloc.h"]:::node
        atomicvar_h_A["atomicvar.h"]:::node

        NE_A --> ae_c_A
        NE_A --> ae_h_A
        NE_A --> ae_epoll_A
        NE_A --> ae_kqueue_A
        NE_A --> ae_select_A
        NE_A --> ae_evport_A
        NE_A --> anet_c_A
        NE_A --> anet_h_A
        NE_A --> networking_A

        NE_A --> CP_A
        CP_A --> server_c_A
        CP_A --> server_h_A
        CP_A --> config_c_A
        CP_A --> config_h_A

        CP_A --> JS_A
        JS_A --> job_c_A
        JS_A --> job_h_A
        JS_A --> queue_c_A
        JS_A --> queue_h_A
        JS_A --> object_c_A
        JS_A --> dict_c_A
        JS_A --> dict_h_A

        JS_A --> CB_A
        CB_A --> cluster_c_A
        CB_A --> cluster_h_A

        JS_A --> AOF_A
        CP_A --> AOF_A
        AOF_A --> aof_c_A
        AOF_A --> rio_c_A
        AOF_A --> rio_h_A
        AOF_A --> disque_check_A

        JS_A --> UTIL_A
        UTIL_A --> util_c_A
        UTIL_A --> util_h_A
        UTIL_A --> zmalloc_c_A
        UTIL_A --> zmalloc_h_A
        UTIL_A --> atomicvar_h_A
    end

    subgraph "Disque Node B"
        direction TB
        NE_B["Network / Event Loop"]:::node
        CP_B["Command Processor"]:::node
        JS_B["Job Store & Queues"]:::node
        CB_B["Cluster Bus"]:::cluster
        AOF_B["AOF Persistence"]:::persistence
    end

    Clients -->|"TCP Commands"| NE_A
    Clients -->|"TCP Commands"| NE_B

    NE_A --> CP_A
    CP_A --> JS_A
    JS_A --> CB_A
    CB_A --> JS_A
    CP_A --> AOF_A

    NE_B --> CP_B
    CP_B --> JS_B
    JS_B --> CB_B
    CB_B --> JS_B
    CP_B --> AOF_B

    CB_A -.->|"Cluster Link"| CB_B
    CB_B -.->|"Cluster Link"| CB_A

    click ae_c_A "https://github.com/antirez/disque/blob/master/src/ae.c"
    click ae_h_A "https://github.com/antirez/disque/blob/master/src/ae.h"
    click ae_epoll_A "https://github.com/antirez/disque/blob/master/src/ae_epoll.c"
    click ae_kqueue_A "https://github.com/antirez/disque/blob/master/src/ae_kqueue.c"
    click ae_select_A "https://github.com/antirez/disque/blob/master/src/ae_select.c"
    click ae_evport_A "https://github.com/antirez/disque/blob/master/src/ae_evport.c"
    click anet_c_A "https://github.com/antirez/disque/blob/master/src/anet.c"
    click anet_h_A "https://github.com/antirez/disque/blob/master/src/anet.h"
    click networking_A "https://github.com/antirez/disque/blob/master/src/networking.c"
    click server_c_A "https://github.com/antirez/disque/blob/master/src/server.c"
    click server_h_A "https://github.com/antirez/disque/blob/master/src/server.h"
    click config_c_A "https://github.com/antirez/disque/blob/master/src/config.c"
    click config_h_A "https://github.com/antirez/disque/blob/master/src/config.h"
    click job_c_A "https://github.com/antirez/disque/blob/master/src/job.c"
    click job_h_A "https://github.com/antirez/disque/blob/master/src/job.h"
    click queue_c_A "https://github.com/antirez/disque/blob/master/src/queue.c"
    click queue_h_A "https://github.com/antirez/disque/blob/master/src/queue.h"
    click object_c_A "https://github.com/antirez/disque/blob/master/src/object.c"
    click dict_c_A "https://github.com/antirez/disque/blob/master/src/dict.c"
    click dict_h_A "https://github.com/antirez/disque/blob/master/src/dict.h"
    click cluster_c_A "https://github.com/antirez/disque/blob/master/src/cluster.c"
    click cluster_h_A "https://github.com/antirez/disque/blob/master/src/cluster.h"
    click aof_c_A "https://github.com/antirez/disque/blob/master/src/aof.c"
    click rio_c_A "https://github.com/antirez/disque/blob/master/src/rio.c"
    click rio_h_A "https://github.com/antirez/disque/blob/master/src/rio.h"
    click disque_check_A "https://github.com/antirez/disque/blob/master/src/disque-check-aof.c"
    click util_c_A "https://github.com/antirez/disque/blob/master/src/util.c"
    click util_h_A "https://github.com/antirez/disque/blob/master/src/util.h"
    click zmalloc_c_A "https://github.com/antirez/disque/blob/master/src/zmalloc.c"
    click zmalloc_h_A "https://github.com/antirez/disque/blob/master/src/zmalloc.h"
    click atomicvar_h_A "https://github.com/antirez/disque/blob/master/src/atomicvar.h"
```
