🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

📬 धडा 07 — Queues आणि async काम: पटकन उत्तर द्या, सावकाश काम नंतर करा

📍 तुम्ही इथे आहात: 18 पैकी धडा 07 · मागे: lesson-06-load-balancing · पुढे: lesson-08-events

📦 या ब्रँचमध्ये काय आहे

धडे 01–06, आणि queue. एक तातडीची सूचना 5 million पालकांपर्यंत SMS ने पोहोचायला हवी — ते काम शिक्षिकेच्या request च्या आत चालता कामा नये. Request सूचना save करतो, queue वर एक job ठेवतो आणि 201 उत्तर देतो. Workers jobs घेतात, batches मध्ये पाठवतात, backoff सह retry करतात आणि अपयशी jobs dead-letter queue (DLQ) मध्ये ठेवतात. Delivery at-least-once असते, म्हणून प्रत्येक consumer idempotent असायला हवा. design/demo.py मधील queues() workers ची संख्या वेग कसा ठरवते ते दाखवते.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

एक शिक्षिका तातडीची सूचना घेऊन येते: "उद्या शाळा बंद — प्रत्येक पालकाला कळवा." खिडकीवरच्या कारकुनाने स्वतःच 5 million पालकांना फोन केले, तर शिक्षिका दिवसेंदिवस खिडकीवर थांबून राहील, आणि तिच्या मागची रांग फाटकाबाहेर जाईल.

म्हणून दीपिका खिडकीवर एक ट्रे 📥 ठेवते. कारकून एक चिठ्ठी लिहिते — "सूचना 42 बद्दल प्रत्येक पालकाला फोन करा" — ती ट्रेमध्ये टाकते, आणि शिक्षिकेला सांगते: "झाले, ते मार्गावर आहे." शिक्षिका एका मिनिटात निघून जाते.

मागच्या खोलीत, मदतनीस ट्रेमधून चिठ्ठ्या घेतात आणि फोन करतात. जास्त मदतनीस, जलद फोन. एखादी मदतनीस चिठ्ठी अर्धवट असताना चक्कर येऊन पडली, तर थोड्या वेळाने ती चिठ्ठी परत ट्रेमध्ये जाते, आणि दुसरी मदतनीस ती घेते — म्हणून काही पालकांना फोन दोनदा येऊ शकतो. प्रत्येक मदतनीस आधी एक यादी तपासत असेल तर हे ठीक आहे: "सूचना 42 बद्दल या पालकाला आधीच कोणी फोन केला आहे का?"

पुन्हा पुन्हा अपयशी होणारी चिठ्ठी (चुकीचा नंबर) कायमची फिरत राहत नाही. ती एखाद्या व्यक्तीने पाहावी म्हणून बाजूच्या ट्रेमध्ये जाते.

🗺️ आकृती

flowchart LR
    t["✍️ teacher: POST urgent notice"] --> api["🔌 API<br/>save notice + 1 job<br/>→ 201 in ~50 ms"]
    api --> q[["📬 queue"]]
    q --> w1["👷 worker"]
    q --> w2["👷 worker"]
    q --> w3["👷 … 50 workers"]
    w1 --> sms["📱 SMS provider<br/>batches of 500"]
    w2 --> sms
    w3 --> sms
    w1 -.->|"no 'done' in time → visible again"| q
    q -.->|"failed 5 times"| dlq[["🧺 DLQ"]]
    note["50 workers × 50 SMS/s<br/>→ 5M in 33.3 min"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/system-design/lesson-diagrams.html#l07

❓ काय

Synchronous — बोलावणारा काम पूर्ण होईपर्यंत थांबतो. User ला आत्ता दिसायला हवे त्यासाठी योग्य (सूचनांची यादी).
Asynchronous — बोलावणाऱ्याला लगेच "स्वीकारले" मिळते; काम नंतर होते. हळू काम, थांबू शकणारे काम, आणि हळू किंवा बेभरवशाच्या बाहेरच्या service शी बोलणारे काम (SMS, email, video encoding, reports) यांसाठी योग्य.
Queue — producer (API) आणि consumers (workers) यांच्यामधली jobs ची टिकाऊ यादी. ती गर्दी शोषून घेते: jobs request मध्ये नाही, queue मध्ये थांबतात.
Worker — job घेणारी, ते करणारी, आणि मग done म्हणणारी (तो delete करणारी) process. जलद जाण्यासाठी workers जोडा; वेग म्हणजे तुम्ही ज्याचे पैसे देता ते.
At-least-once delivery — बहुतेक queues (SQS standard, RabbitMQ, Kafka consumers) प्रत्येक job किमान एकदा पोहोचवण्याचे वचन देतात — कधी कधी दोनदा. Exactly-once processing ही तुम्ही बांधायची गोष्ट आहे, आपोआप मिळणारी नाही.
Visibility timeout — worker job घेतो तेव्हा queue तो N सेकंद लपवते. Worker ने वेळेत "done" म्हटले नाही (तो crash झाला, किंवा हळू होता), तर job पुन्हा दिसू लागतो आणि दुसरा worker तो घेतो. तो सर्वात हळू सामान्य job पेक्षा जास्त ठेवा.
Backoff सह retries — प्रत्येक अपयशानंतर जास्त वेळ थांबा (1 s, 2 s, 4 s … jitter सह), म्हणजे आधीच अडचणीत असलेल्या SMS provider वर सतत मारा होत नाही.
Dead-letter queue (DLQ) — N अपयशी प्रयत्नांनंतर job माणसासाठी किंवा नंतरच्या redrive साठी बाजूला जातो. ती रिकामी नसेल तेव्हा alert द्या.
Idempotent consumer — तोच job दोनदा process केला तरी परिणाम एकदा केल्यासारखाच: "(सूचना 42, पालक 17) पाठवले" अशी table ठेवा आणि नोंद असेल तर वगळा.
Backpressure — workers पूर्ण करतात त्यापेक्षा jobs जलद आले की queue वाढते. सर्वात जुन्या job चे वय पाहा, backlog नुसार workers वाढवा, आणि गरज असेल तर producers ना हळू करा (429, धडा 12).

🤔 का

कारण कागद (धडा 01) म्हणतो "post p99 < 500 ms" आणि "तातडीच्या सूचनांसाठी पालकाला notification मिळते". Request मध्ये 5 million SMS पाठवल्याने पहिले वचन मोडते. Queue दोन्ही पाळते: शिक्षिकेचा request जलद, आणि पाठवणे तुम्ही पैसे देता तितक्या workers इतके जलद. ते अपयश वेगळे ठेवते: SMS provider 10 मिनिटे बंद असला, तर jobs queue मध्ये थांबतात; सूचना post करणे चालूच राहते.

🔧 कसे (या repo मध्ये)

या धड्यासाठी lab मध्ये queue class नाही — model म्हणजे गणित, आणि तोच मुद्दा आहे: वेळ = jobs ÷ (workers × प्रत्येक worker चा वेग). design/demo.py मधील queues() प्रत्येकी सेकंदाला 50 SMS या वेगाने 10, 50 आणि 200 workers साठी ते छापते. Snippet वेग बदलतो, jobs बाहेर जाण्यापेक्षा जलद येतात असे एक गर्दीचे मिनिट जोडतो (backlog), आणि एकच job दोनदा मिळणारा एक idempotent consumer चालवतो.

🧪 करून पाहा

python3 design/demo.py queues
python3 - <<'EOF'
jobs = 5_000_000
for workers, rate in ((50, 50), (50, 25), (100, 50), (50, 5)):
    print(f"{workers:>3} workers × {rate:>2} SMS/s → {jobs / (workers * rate) / 60:6.1f} min")
arrive, drain = 3_000, 2_500           # per second, for one busy minute
print(f"backlog after 60 s: {(arrive - drain) * 60:,} jobs waiting · cleared {(arrive - drain) * 60 / drain:.0f} s after the rush")
# at-least-once: message 2 is delivered twice (the worker crashed before it said 'done')
deliveries = ["sms-1", "sms-2", "sms-2", "sms-3"]
sent, done = [], set()
for m in deliveries:
    if m in done: continue                  # idempotent consumer: already handled
    sent.append(m); done.add(m)
print("delivered", len(deliveries), "· sent", len(sent), sent)
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

queues छापते:

── 'send 5M urgent SMS' must not run inside the request
   request: save the notice, put ONE job on a queue, answer 201 in ~50 ms
   workers: take jobs, send in batches of 500, retry with backoff, park failures in a DLQ
    10 workers × 50 SMS/s → all 5M sent in  166.7 min
    50 workers × 50 SMS/s → all 5M sent in   33.3 min
   200 workers × 50 SMS/s → all 5M sent in    8.3 min
   queues decouple speed: the request is fast, the work is as fast as you pay for · delivery is at-least-once

तुमचा snippet छापतो:

 50 workers × 50 SMS/s →   33.3 min
 50 workers × 25 SMS/s →   66.7 min
100 workers × 50 SMS/s →   16.7 min
 50 workers ×  5 SMS/s →  333.3 min
backlog after 60 s: 30,000 jobs waiting · cleared 12 s after the rush
delivered 4 · sent 3 ['sms-1', 'sms-2', 'sms-3']

🏁 तुम्ही आत्ताच काय सिद्ध केले

शिक्षिकेला उत्तर मिळण्याची वेळ यांपैकी कोणत्याच आकड्यावर अवलंबून नाही — तो एक queue write आहे. कामाची वेळ अवलंबून आहे: वेग निम्मा करा आणि ती दुप्पट होते; workers दुप्पट करा आणि ती निम्मी होते; हळू provider (5 SMS/s) 33 मिनिटांचे 5.5 तास करतो. गर्दी एक backlog मागे ठेवते जो गर्दीच्या वेळी requests अपयशी करण्याऐवजी गर्दी नंतर रिकामा होतो. आणि दोनदा पोहोचलेला job एकदाच पाठवला गेला, कारण consumer ने आधी तपासले.

⚠️ नेहमीच्या चुका

हळू बाहेरचे calls (SMS, email, PDF) request च्या आत करणे
exactly-once गृहीत धरणे: idempotency तपासणी नाही, म्हणून worker restart नंतर पालकांना दोन SMS येतात
job पेक्षा लहान visibility timeout — दोन workers एकाच वेळी तोच job करतात
DLQ नाही: एक वाईट message कायम retry होत राहतो आणि इतरांना अडवतो
कोणीही लक्ष न देणारी DLQ
user थांबलेला असतो अशा read साठी queue वापरणे — ते कमी नव्हे, जास्त थांबतात
queue depth किंवा सर्वात जुन्या message च्या वयाऐवजी CPU वर workers वाढवणे
SMS provider परवानगी देतो त्यापेक्षा जास्त workers — आता सगळेच throttle होतात (मर्यादा ही constraint आहे, धडा 01)

🏭 प्रत्यक्ष वापरात

On a real account — 5 प्रयत्नांनंतर DLQ असलेली, आणि एका batch पेक्षा जास्त visibility timeout असलेली SQS queue:

aws sqs create-queue --queue-name urgent-sms-dlq \
    --attributes MessageRetentionPeriod=1209600
aws sqs create-queue --queue-name urgent-sms --attributes '{
  "VisibilityTimeout": "120",
  "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:ap-south-1:123456789012:urgent-sms-dlq\",\"maxReceiveCount\":\"5\"}"
}'

Batch मधले फक्त अपयशी messages कळवणारा Lambda consumer (म्हणजे चांगले messages पुन्हा retry होत नाहीत), SMS provider ची मर्यादा पाळण्यासाठी concurrency वर कमाल मर्यादेसह:

aws lambda create-event-source-mapping --function-name send-sms \
    --event-source-arn arn:aws:sqs:ap-south-1:123456789012:urgent-sms \
    --batch-size 10 --function-response-types ReportBatchItemFailures \
    --scaling-config MaximumConcurrency=50

Idempotency तपासणी, database मधील unique key च्या रूपात:

CREATE TABLE sms_sent (notice_id bigint, parent_id bigint, PRIMARY KEY (notice_id, parent_id));
INSERT INTO sms_sent VALUES ($1, $2) ON CONFLICT DO NOTHING;   -- 0 rows inserted → already sent, skip

अधिक खोलात: Scaling शाळा, धडे 12 (SQS, backlog नुसार वाढणारे workers) आणि 13 (idempotency, DLQs).

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: फक्त queue च्या लांबीवर नाही, तर ApproximateAgeOfOldestMessage वर alarm लावा. "सर्वात जुना तातडीचा SMS 20 मिनिटे थांबला आहे" हा पालकाला जाणवणारा आकडा आहे.

⏭️ पुढे

एक सूचना, आणि आता चार jobs व्हायला हवेत: SMS, email, search index, analytics. API ने प्रत्येकाला call करावा का? नियोजन कार्यालय एका घटनेची घोषणा करते आणि प्रत्येक ऐकणाऱ्याला प्रतिसाद देऊ देते — ती कधीही न गमावता.

git checkout lesson-08-events

📬 Lesson 07 — Queues & async work: answer fast, do the slow work later

📍 You are here: Lesson 07 of 18 · Previous: lesson-06-load-balancing · Next: lesson-08-events

📦 What's in this branch

Lessons 01–06, plus the queue. An urgent notice must reach 5 million parents by SMS — that work must not run inside the teacher's request. The request saves the notice, puts one job on a queue and answers 201. Workers take jobs, send in batches, retry with backoff and park failures in a dead-letter queue (DLQ). Delivery is at-least-once, so every consumer must be idempotent. queues() in design/demo.py shows how the number of workers sets the speed.

🧒 Explain like I'm 5

A teacher brings an urgent notice: "School closed tomorrow — tell every parent." If the clerk at the counter phones 5 million parents herself, the teacher waits at the counter for days, and the queue behind her goes out of the gate.

So Dipika puts a tray 📥 on the counter. The clerk writes one slip — "phone every parent about notice 42" — drops it in the tray, and says to the teacher: "Done, it is on its way." The teacher leaves after one minute.

In the back room, helpers take slips from the tray and make the calls. More helpers, faster calls. If a helper faints halfway through a slip, the slip goes back into the tray after a while, and another helper takes it — so a few parents may get the call twice. That is fine if every helper first checks a list: "did someone already call this parent about notice 42?"

A slip that fails again and again (a wrong number) does not go round forever. It goes to a side tray for a person to look at.

🗺️ Diagram

flowchart LR
    t["✍️ teacher: POST urgent notice"] --> api["🔌 API<br/>save notice + 1 job<br/>→ 201 in ~50 ms"]
    api --> q[["📬 queue"]]
    q --> w1["👷 worker"]
    q --> w2["👷 worker"]
    q --> w3["👷 … 50 workers"]
    w1 --> sms["📱 SMS provider<br/>batches of 500"]
    w2 --> sms
    w3 --> sms
    w1 -.->|"no 'done' in time → visible again"| q
    q -.->|"failed 5 times"| dlq[["🧺 DLQ"]]
    note["50 workers × 50 SMS/s<br/>→ 5M in 33.3 min"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/system-design/lesson-diagrams.html#l07

❓ What

Synchronous — the caller waits for the work to finish. Right for what the user must see now (the notice list).
Asynchronous — the caller gets "accepted" at once; the work happens later. Right for slow work, work that can wait, and work that talks to a slow or flaky outside service (SMS, email, video encoding, reports).
Queue — a durable list of jobs between a producer (the API) and consumers (workers). It absorbs bursts: jobs wait in the queue, not in the request.
Worker — a process that takes a job, does it, then says done (deletes it). Add workers to go faster; the speed is what you pay for.
At-least-once delivery — most queues (SQS standard, RabbitMQ, Kafka consumers) promise every job is delivered at least once — sometimes twice. Exactly-once processing is something you build, not something you get.
Visibility timeout — when a worker takes a job, the queue hides it for N seconds. If the worker does not say "done" in time (it crashed, or was slow), the job becomes visible again and another worker takes it. Set it longer than the slowest normal job.
Retries with backoff — wait longer after each failure (1 s, 2 s, 4 s … with jitter) so a struggling SMS provider is not hammered.
Dead-letter queue (DLQ) — after N failed attempts, the job moves aside for a human or a later redrive. Alert when it is not empty.
Idempotent consumer — processing the same job twice has the same effect as once: keep a table of "(notice 42, parent 17) sent" and skip if present.
Backpressure — when jobs arrive faster than workers finish, the queue grows. Watch the age of the oldest job, scale workers on the backlog, and if needed slow the producers (429, lesson 12).

🤔 Why

Because the sheet (lesson 01) says "post p99 < 500 ms" and "a parent gets a notification for urgent notices". Sending 5 million SMS in the request breaks the first promise. The queue keeps both: the teacher's request is fast, and the sending is as fast as the number of workers you pay for. It also isolates failure: if the SMS provider is down for 10 minutes, jobs wait in the queue; posting notices keeps working.

🔧 How (in this repo)

The lab has no queue class for this lesson — the model is arithmetic, and that is the point: time = jobs ÷ (workers × rate per worker). queues() in design/demo.py prints it for 10, 50 and 200 workers at 50 SMS a second each. The snippet changes the rate, adds a busy minute where jobs arrive faster than they leave (a backlog), and runs an idempotent consumer that receives one job twice.

🧪 Try it

python3 design/demo.py queues
python3 - <<'EOF'
jobs = 5_000_000
for workers, rate in ((50, 50), (50, 25), (100, 50), (50, 5)):
    print(f"{workers:>3} workers × {rate:>2} SMS/s → {jobs / (workers * rate) / 60:6.1f} min")
arrive, drain = 3_000, 2_500           # per second, for one busy minute
print(f"backlog after 60 s: {(arrive - drain) * 60:,} jobs waiting · cleared {(arrive - drain) * 60 / drain:.0f} s after the rush")
# at-least-once: message 2 is delivered twice (the worker crashed before it said 'done')
deliveries = ["sms-1", "sms-2", "sms-2", "sms-3"]
sent, done = [], set()
for m in deliveries:
    if m in done: continue                  # idempotent consumer: already handled
    sent.append(m); done.add(m)
print("delivered", len(deliveries), "· sent", len(sent), sent)
EOF

✅ Verify — what you should see

queues prints:

── 'send 5M urgent SMS' must not run inside the request
   request: save the notice, put ONE job on a queue, answer 201 in ~50 ms
   workers: take jobs, send in batches of 500, retry with backoff, park failures in a DLQ
    10 workers × 50 SMS/s → all 5M sent in  166.7 min
    50 workers × 50 SMS/s → all 5M sent in   33.3 min
   200 workers × 50 SMS/s → all 5M sent in    8.3 min
   queues decouple speed: the request is fast, the work is as fast as you pay for · delivery is at-least-once

Your snippet prints:

 50 workers × 50 SMS/s →   33.3 min
 50 workers × 25 SMS/s →   66.7 min
100 workers × 50 SMS/s →   16.7 min
 50 workers ×  5 SMS/s →  333.3 min
backlog after 60 s: 30,000 jobs waiting · cleared 12 s after the rush
delivered 4 · sent 3 ['sms-1', 'sms-2', 'sms-3']

🏁 What you just proved

The teacher's answer time does not depend on any of these numbers — it is one queue write. The work time does: halve the rate and it doubles; double the workers and it halves; a slow provider (5 SMS/s) turns 33 minutes into 5.5 hours. A burst leaves a backlog that drains after the rush instead of failing requests during it. And a job delivered twice was sent once, because the consumer checked first.

⚠️ Common mistakes

doing slow outside calls (SMS, email, PDF) inside the request
assuming exactly-once: no idempotency check, so parents get two SMS after a worker restart
a visibility timeout shorter than the job — two workers do the same job at once
no DLQ: one bad message is retried forever and blocks others
a DLQ nobody watches
a queue used for a read the user is waiting for — they wait longer, not shorter
scaling workers on CPU instead of on queue depth or the age of the oldest message
more workers than the SMS provider allows — now they all get throttled (a limit is a constraint, lesson 01)

🏭 In production

On a real account — an SQS queue with a DLQ after 5 attempts and a visibility timeout longer than one batch:

aws sqs create-queue --queue-name urgent-sms-dlq \
    --attributes MessageRetentionPeriod=1209600
aws sqs create-queue --queue-name urgent-sms --attributes '{
  "VisibilityTimeout": "120",
  "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:ap-south-1:123456789012:urgent-sms-dlq\",\"maxReceiveCount\":\"5\"}"
}'

A Lambda consumer that reports only the failed messages of a batch (so the good ones are not retried), with a ceiling on concurrency to respect the SMS provider's limit:

aws lambda create-event-source-mapping --function-name send-sms \
    --event-source-arn arn:aws:sqs:ap-south-1:123456789012:urgent-sms \
    --batch-size 10 --function-response-types ReportBatchItemFailures \
    --scaling-config MaximumConcurrency=50

The idempotency check, as a unique key in the database:

CREATE TABLE sms_sent (notice_id bigint, parent_id bigint, PRIMARY KEY (notice_id, parent_id));
INSERT INTO sms_sent VALUES ($1, $2) ON CONFLICT DO NOTHING;   -- 0 rows inserted → already sent, skip

Go deeper: the Scaling school, lessons 12 (SQS, workers that scale on backlog) and 13 (idempotency, DLQs).

🏭 Why this matters in production: alarm on ApproximateAgeOfOldestMessage, not only on queue length. "The oldest urgent SMS has waited 20 minutes" is the number a parent feels.

⏭️ Next

One notice, and now four jobs want to happen: SMS, email, the search index, analytics. Should the API call each one? The planning office announces a fact and lets each listener react — without ever losing it.

git checkout lesson-08-events

← Previousload balancing Next →events

This page is the lesson's README from the lesson-07-queues branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.