Async/Await and Promises — غیر متزامن پروگرامنگ

The Urdu Programming Language runs on Python's asyncio and supports full asynchronous programming. This document covers async functions, await, promises, concurrent operations, and generator-based async patterns.

اردو: اردو پروگرامنگ لینگویج Python کے asyncio پر چلتی ہے اور مکمل غیر متزامن پروگرامنگ کی حمایت کرتی ہے۔ یہ دستاویز غیر_متزامن فنکشنز، انتظار، وعدے، بیک وقت آپریشنز، اور جنریٹر پر مبنی غیر متزامن طریقوں کا احاطہ کرتی ہے۔

---

Table of Contents

1. Why Async?
2. غیر_متزامن فنکشن — async function
3. انتظار — await
4. تاخیر() — Delay
5. وعدہ — Promise
6. Chaining Promises
7. انتظار_سبھی() — Promise.all
8. Promise.allSettled / race / any
9. Async Error Handling
10. Generator Functions with پیداوار
11. Async Generators
12. Concurrent Operations Example

---

Why Async? — غیر متزامن پروگرامنگ کیوں؟

Asynchronous code lets your program continue working while waiting for slow operations (network, disk, timers) instead of blocking the entire thread.

اردو: غیر متزامن کوڈ آپ کے پروگرام کو سست آپریشنز (نیٹ ورک، ڈسک، ٹائمر) کا انتظار کرتے وقت کام جاری رکھنے دیتا ہے، بجائے اس کے کہ پورا دھاگہ رک جائے۔

// Synchronous — blocks everything
فنکشن ہم_وقت() {
    لکھو("شروع");
    // imagine 2 seconds of blocking work here
    لکھو("مکمل");
}

// Asynchronous — non-blocking
غیر_متزامن فنکشن غیر_ہم_وقت() {
    لکھو("شروع");
    انتظار تاخیر(2000);    // suspends only this function
    لکھو("2 سیکنڈ بعد مکمل");
}

---

غیر_متزامن فنکشن — async function

Prefix any function with غیر_متزامن to make it async. An async function always returns a Promise.

اردو: کسی بھی فنکشن کے آگے غیر_متزامن لگانے سے وہ غیر متزامن بن جاتا ہے۔ غیر متزامن فنکشن ہمیشہ ایک وعدہ واپس کرتا ہے۔

غیر_متزامن فنکشن ڈیٹا_حاصل_کرو() {
    واپس "ڈیٹا ملا";
}

// Calling it returns a Promise
مستقل وعدہ_شے = ڈیٹا_حاصل_کرو();
لکھو(وعدہ_شے);    // Promise { "ڈیٹا ملا" }

// Await it
مستقل نتیجہ = انتظار ڈیٹا_حاصل_کرو();
لکھو(نتیجہ);       // ڈیٹا ملا

Async arrow function:

اردو: غیر متزامن تیر فنکشن:

مستقل سلام = غیر_متزامن (نام) => {
    انتظار تاخیر(100);
    واپس `مرحبا، ${نام}!`;
};

لکھو(انتظار سلام("احمد"));    // مرحبا، احمد!

Async method in class:

اردو: کلاس میں غیر متزامن طریقہ:

کلاس API_کلائنٹ {
    تعمیر(بنیادی_url) {
        یہ.بنیادی_url = بنیادی_url;
    }

    غیر_متزامن حاصل_کرو(راستہ) {
        مستقل جواب = انتظار کرل(`${یہ.بنیادی_url}${راستہ}`);
        واپس JSON_پڑھو(جواب);
    }

    غیر_متزامن بھیجو(راستہ, ڈیٹا) {
        مستقل جواب = انتظار کرل(`${یہ.بنیادی_url}${راستہ}`, {
            طریقہ: "POST",
            جسم: JSON_لکھو(ڈیٹا)
        });
        واپس JSON_پڑھو(جواب);
    }
}

---

انتظار — await

انتظار pauses the async function until the Promise resolves, then returns the resolved value.

اردو: انتظار غیر متزامن فنکشن کو اس وقت تک روکتا ہے جب تک وعدہ پورا نہ ہو جائے، پھر حل شدہ قدر واپس کرتا ہے۔

غیر_متزامن فنکشن مثال() {
    لکھو("مرحلہ 1");
    انتظار تاخیر(500);
    لکھو("مرحلہ 2 — 500ms بعد");
    انتظار تاخیر(500);
    لکھو("مرحلہ 3 — 1000ms بعد");
}

انتظار مثال();

Await any Promise:

اردو: کسی بھی وعدے کا انتظار:

غیر_متزامن فنکشن ڈیٹا_لوڈ() {
    // Simulated async fetch
    مستقل ڈیٹا = انتظار نیا وعدہ(حل => {
        setTimeout(() => حل({ نام: "احمد", سکور: 95 }), 100);
    });

    لکھو(ڈیٹا.نام);    // احمد
    واپس ڈیٹا;
}

مستقل نتیجہ = انتظار ڈیٹا_لوڈ();

---

تاخیر() — Delay

تاخیر(ms) is a built-in that returns a Promise resolving after ms milliseconds.

اردو: تاخیر(ms) ایک بنا بنایا فنکشن ہے جو ms ملی سیکنڈ کے بعد حل ہونے والا وعدہ واپس کرتا ہے۔

غیر_متزامن فنکشن الٹی_گنتی(سے) {
    کے_لیے (متغیر i کا حد(سے, 0, -1)) {
        لکھو(i);
        انتظار تاخیر(1000);
    }
    لکھو("🚀 لانچ!");
}

انتظار الٹی_گنتی(5);
// 5  (انتظار 1s)
// 4  (انتظار 1s)
// ...
// 🚀 لانچ!

// Retry pattern using تاخیر
غیر_متزامن فنکشن دوبارہ_کوشش(فنکشن_شے, کوشش = 3, وقفہ = 1000) {
    کے_لیے (متغیر i کا حد(کوشش)) {
        کوشش {
            واپس انتظار فنکشن_شے();
        } پکڑو (غ) {
            اگر (i === کوشش - 1) پھینکو غ;
            لکھو(`کوشش ${i + 1} ناکام، ${وقفہ}ms بعد دوبارہ...`);
            انتظار تاخیر(وقفہ);
        }
    }
}

---

وعدہ — Promise

A وعدہ (Promise) represents a future value. It is created with a callback that receives حل (resolve) and رد (reject) functions.

اردو: وعدہ ایک مستقبل کی قدر کو ظاہر کرتا ہے۔ اسے ایک کال بیک کے ساتھ بنایا جاتا ہے جو حل (resolve) اور رد (reject) فنکشن وصول کرتا ہے۔

مستقل سکہ_اچھالو = نیا وعدہ((حل, رد) => {
    مستقل نتیجہ = اتفاقی() > 0.5 ? "چت" : "پٹ";
    setTimeout(() => حل(نتیجہ), 100);
});

مستقل نتیجہ = انتظار سکہ_اچھالو;
لکھو(نتیجہ);    // چت  یا  پٹ

// Promise that can reject
غیر_متزامن فنکشن تقسیم(الف, ب) {
    واپس نیا وعدہ((حل, رد) => {
        اگر (ب === 0) {
            رد(نیا Error("صفر سے تقسیم ناممکن"));
        } ورنہ {
            حل(الف / ب);
        }
    });
}

لکھو(انتظار تقسیم(10, 2));    // 5

Promise states:

اردو: وعدے کی حالتیں:

State	Meaning
Pending	Not yet settled
Fulfilled	Resolved with a value
Rejected	Rejected with a reason

---

Chaining Promises — وعدوں کا سلسلہ

Use .پھر() (then), .پکڑو() (catch), and .آخر() (finally) for promise chains.

اردو: وعدوں کی زنجیر بنانے کے لیے .پھر() (then)، .پکڑو() (catch)، اور .آخر() (finally) استعمال کریں۔

تقسیم(100, 5)
    .پھر(نتیجہ => {
        لکھو(`پہلا نتیجہ: ${نتیجہ}`);
        واپس تقسیم(نتیجہ, 2);
    })
    .پھر(نتیجہ => {
        لکھو(`دوسرا نتیجہ: ${نتیجہ}`);
    })
    .پکڑو(غلطی => {
        لکھو(`غلطی: ${غلطی.message}`);
    })
    .آخر(() => {
        لکھو("سلسلہ مکمل");
    });

---

انتظار_سبھی() — Promise.all

انتظار_سبھی(وعدے) runs all promises concurrently and waits until all resolve. If any rejects, the whole call rejects.

اردو: انتظار_سبھی(وعدے) تمام وعدے بیک وقت چلاتا ہے اور سب کے پورا ہونے کا انتظار کرتا ہے۔ اگر کوئی ایک رد ہو جائے تو پوری کال رد ہو جاتی ہے۔

غیر_متزامن فنکشن آہستہ_کام(نام, ملی_سیکنڈ) {
    انتظار تاخیر(ملی_سیکنڈ);
    واپس `${نام} مکمل (${ملی_سیکنڈ}ms)`;
}

غیر_متزامن فنکشن تمام_کام() {
    مستقل شروع = وقت();

    مستقل نتائج = انتظار انتظار_سبھی([
        آہستہ_کام("کام الف", 300),
        آہستہ_کام("کام ب",   200),
        آہستہ_کام("کام ج",   400)
    ]);

    مستقل وقت_لگا = وقت() - شروع;
    لکھو(نتائج);
    لکھو(`کل وقت: ~${وقت_لگا}ms`);    // ~400ms, not 900ms
}

انتظار تمام_کام();
// ["کام الف مکمل (300ms)", "کام ب مکمل (200ms)", "کام ج مکمل (400ms)"]
// کل وقت: ~400ms

// Parallel data loading
غیر_متزامن فنکشن ڈیش_بورڈ_لوڈ() {
    مستقل [صارفین, آرڈر, مصنوعات] = انتظار انتظار_سبھی([
        API.حاصل_کرو("/صارفین"),
        API.حاصل_کرو("/آرڈر"),
        API.حاصل_کرو("/مصنوعات")
    ]);

    واپس { صارفین, آرڈر, مصنوعات };
}

---

Promise.allSettled / race / any

Promise.allSettled — تمام_نتائج()

Waits for all promises regardless of outcome. Returns an array of { status, value/reason } objects.

اردو: تمام وعدوں کا انتظار کرتا ہے چاہے نتیجہ کچھ بھی ہو۔ { status, value/reason } اشیاء کی فہرست واپس کرتا ہے۔

غیر_متزامن فنکشن مثال_نتائج() {
    مستقل نتائج = انتظار Promise.allSettled([
        وعدہ.resolve("کامیاب"),
        وعدہ.reject("ناکام"),
        وعدہ.resolve("بھی کامیاب")
    ]);

    کے_لیے (مستقل نتیجہ کا نتائج) {
        اگر (نتیجہ.status === "fulfilled") {
            لکھو(`کامیاب: ${نتیجہ.value}`);
        } ورنہ {
            لکھو(`ناکام: ${نتیجہ.reason}`);
        }
    }
}

Promise.race — دوڑ()

Resolves or rejects as soon as the first promise settles.

اردو: جیسے ہی پہلا وعدہ طے ہو جائے، حل یا رد ہو جاتا ہے۔

// Timeout pattern
غیر_متزامن فنکشن ٹائم_آؤٹ_کے_ساتھ(وعدہ_شے, ملی_سیکنڈ) {
    مستقل ٹائم_آؤٹ_وعدہ = نیا وعدہ((_, رد) =>
        setTimeout(() => رد(نیا Error("وقت ختم")), ملی_سیکنڈ)
    );
    واپس Promise.race([وعدہ_شے, ٹائم_آؤٹ_وعدہ]);
}

کوشش {
    مستقل نتیجہ = انتظار ٹائم_آؤٹ_کے_ساتھ(
        آہستہ_کام("ڈیٹا", 5000),
        2000    // 2 second timeout
    );
    لکھو(نتیجہ);
} پکڑو (غ) {
    لکھو(`${غ.message}`);    // وقت ختم
}

Promise.any — کوئی_ایک()

Resolves with the first successful promise.

اردو: پہلے کامیاب وعدے کے ساتھ حل ہوتا ہے۔

مستقل نتیجہ = انتظار Promise.any([
    وعدہ.reject("سرور 1 ناکام"),
    آہستہ_کام("سرور 2", 200),
    آہستہ_کام("سرور 3", 100)
]);
لکھو(نتیجہ);    // سرور 3 مکمل (100ms)

---

Async Error Handling — غیر متزامن غلطی سنبھالنا

Always wrap انتظار calls in کوشش/پکڑو to handle rejections gracefully.

اردو: ردّ کو سلیقے سے سنبھالنے کے لیے انتظار کالز کو ہمیشہ کوشش/پکڑو میں لپیٹیں۔

غیر_متزامن فنکشن محفوظ_طریقے_سے() {
    کوشش {
        مستقل ڈیٹا = انتظار کرل("https://api.example.com/users");
        مستقل صارفین = JSON_پڑھو(ڈیٹا);
        لکھو(`${صارفین.لمبائی} صارفین ملے`);
    } پکڑو (غ) {
        لکھو(`نیٹ ورک غلطی: ${غ.message}`);
    } آخر {
        لکھو("درخواست مکمل");
    }
}

// Handle different error types
غیر_متزامن فنکشن ڈیٹا_پروسیس() {
    کوشش {
        مستقل جواب = انتظار کرل("https://api.example.com/data");
        اگر (!جواب.ok) پھینکو نیا Error(`HTTP ${جواب.status}`);
        واپس انتظار جواب.json();
    } پکڑو (غ) {
        اگر (غ مثال TypeError) {
            لکھو("نیٹ ورک سے رابطہ نہیں");
        } ورنہ_اگر (غ.message.شروع_ہے("HTTP")) {
            لکھو(`سرور غلطی: ${غ.message}`);
        } ورنہ {
            لکھو(`نامعلوم غلطی: ${غ.message}`);
        }
        واپس خالی;
    }
}

// Parallel with individual error handling
غیر_متزامن فنکشن محفوظ_سب(وعدے) {
    واپس انتظار_سبھی(
        وعدے.تبدیل(p =>
            p.پکڑو(غ => ({ غلطی: غ.message }))
        )
    );
}

مستقل نتائج = انتظار محفوظ_سب([
    وعدہ.resolve(42),
    وعدہ.reject(نیا Error("ناکام")),
    وعدہ.resolve("مکمل")
]);

لکھو(نتائج);
// [42, { غلطی: "ناکام" }, "مکمل"]

---

Generator Functions with پیداوار — جنریٹر فنکشنز

Generator functions produce values lazily with پیداوار. They are useful for memory-efficient iteration.

اردو: جنریٹر فنکشنز پیداوار کے ساتھ قدریں سست روی سے پیدا کرتے ہیں۔ یہ میموری کے اعتبار سے موثر تکرار کے لیے مفید ہیں۔

فنکشن* فبوناچی() {
    متغیر [الف, ب] = [0, 1];
    جبکہ (سچ) {
        پیداوار الف;
        [الف, ب] = [ب, الف + ب];
    }
}

// Take first 10
مستقل g = فبوناچی();
مستقل پہلے_10 = [];
کے_لیے (متغیر _ کا حد(10)) {
    پہلے_10.شامل(g.اگلا().value);
}
لکھو(پہلے_10);
// [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

// Generator pipeline
فنکشن* نقشہ(اشیاء, fn) {
    کے_لیے (مستقل شے کا اشیاء) {
        پیداوار fn(شے);
    }
}

فنکشن* چھانو(اشیاء, شرط) {
    کے_لیے (مستقل شے کا اشیاء) {
        اگر (شرط(شے)) پیداوار شے;
    }
}

فنکشن* حد_لگاؤ(اشیاء, n) {
    متغیر گنتی = 0;
    کے_لیے (مستقل شے کا اشیاء) {
        اگر (گنتی++ >= n) ٹوٹنا;
        پیداوار شے;
    }
}

// Compose: first 5 even squares from natural numbers
مستقل قدرتی = فنکشن*() { متغیر i = 0; جبکہ(سچ) پیداوار i++; };
مستقل نتیجہ = [...حد_لگاؤ(چھانو(نقشہ(قدرتی(), n => n*n), n => n%2===0), 5)];
لکھو(نتیجہ);    // [0, 4, 16, 36, 64]

---

Async Generators — غیر متزامن جنریٹرز

Async generators combine غیر_متزامن فنکشن* with پیداوار for streaming async data.

اردو: غیر متزامن جنریٹرز غیر_متزامن فنکشن* اور پیداوار کو ملاتے ہیں تاکہ غیر متزامن ڈیٹا کو بہاؤ کی صورت میں حاصل کیا جا سکے۔

غیر_متزامن فنکشن* ڈیٹا_سٹریم(صفحات) {
    کے_لیے (متغیر صفحہ کا حد(1, صفحات + 1)) {
        انتظار تاخیر(200);    // simulate API call
        پیداوار { صفحہ, ڈیٹا: `صفحہ ${صفحہ} کا ڈیٹا` };
    }
}

غیر_متزامن فنکشن سب_صفحات() {
    کے_لیے انتظار (مستقل ٹکڑا کا ڈیٹا_سٹریم(3)) {
        لکھو(ٹکڑا);
    }
}

انتظار سب_صفحات();
// { صفحہ: 1, ڈیٹا: "صفحہ 1 کا ڈیٹا" }
// { صفحہ: 2, ڈیٹا: "صفحہ 2 کا ڈیٹا" }
// { صفحہ: 3, ڈیٹا: "صفحہ 3 کا ڈیٹا" }

---

Concurrent Operations Example — بیک وقت آپریشنز کی مثال

A realistic example showing sequential vs concurrent loading and result handling.

اردو: ایک حقیقی مثال جو بالترتیب بمقابلہ بیک وقت لوڈنگ اور نتائج کا موازنہ دکھاتی ہے۔

// Simulate API calls
غیر_متزامن فنکشن صارف_حاصل_کرو(id) {
    انتظار تاخیر(300);
    واپس { id, نام: `صارف ${id}`, ای_میل: `user${id}@example.com` };
}

غیر_متزامن فنکشن آرڈر_حاصل_کرو(صارف_id) {
    انتظار تاخیر(200);
    واپس [
        { id: صارف_id * 100, شے: "کتاب", قیمت: 500 },
        { id: صارف_id * 100 + 1, شے: "قلم", قیمت: 50 }
    ];
}

// ❌ Sequential — slow (500ms total)
غیر_متزامن فنکشن بالترتیب_لوڈ(ids) {
    مستقل نتائج = [];
    کے_لیے (مستقل id کا ids) {
        مستقل صارف = انتظار صارف_حاصل_کرو(id);
        مستقل آرڈر = انتظار آرڈر_حاصل_کرو(id);
        نتائج.شامل({ صارف, آرڈر });
    }
    واپس نتائج;
}

// ✅ Concurrent — fast (300ms total)
غیر_متزامن فنکشن بیک_وقت_لوڈ(ids) {
    واپس انتظار انتظار_سبھی(
        ids.تبدیل(غیر_متزامن id => {
            مستقل [صارف, آرڈر] = انتظار انتظار_سبھی([
                صارف_حاصل_کرو(id),
                آرڈر_حاصل_کرو(id)
            ]);
            واپس { صارف, آرڈر };
        })
    );
}

مستقل نتائج = انتظار بیک_وقت_لوڈ([1, 2, 3]);

کے_لیے (مستقل { صارف, آرڈر } کا نتائج) {
    مستقل کل = آرڈر.کم_کرو((s, o) => s + o.قیمت, 0);
    لکھو(`${صارف.نام}: ${آرڈر.لمبائی} آرڈر، کل ${کل} روپے`);
}
// صارف 1: 2 آرڈر، کل 550 روپے
// صارف 2: 2 آرڈر، کل 550 روپے
// صارف 3: 2 آرڈر، کل 550 روپے

// Queue — process N items at a time
غیر_متزامن فنکشن متوازی_قطار(اشیاء, fn, ہم_وقت = 3) {
    مستقل نتائج = [];
    کے_لیے (متغیر i = 0; i < اشیاء.لمبائی; i += ہم_وقت) {
        مستقل ٹکڑا = اشیاء.حصہ(i, i + ہم_وقت);
        مستقل ٹکڑا_نتائج = انتظار انتظار_سبھی(ٹکڑا.تبدیل(fn));
        نتائج.جوڑ_دو(...ٹکڑا_نتائج);
    }
    واپس نتائج;
}

مستقل ids = [1, 2, 3, 4, 5, 6, 7, 8];
مستقل صارفین = انتظار متوازی_قطار(ids, صارف_حاصل_کرو, 3);
لکھو(`${صارفین.لمبائی} صارفین لوڈ ہوئے`);    // 8 صارفین لوڈ ہوئے