runBlocking — ما هو، جسر الحظر وكيف يعمل

ما هو runBlocking؟

runBlocking هي دالة Kotlin تنشئ CoroutineScope جديداً وتشغل الكوروتين الممرر، مما يحجر الخيط الحالي حتى اكتماله بالكامل. بالخلاف من جميع منشئات Coroutine الأخرى، runBlocking ليست دالة suspend ويمكن استدعاؤها من كود متزامن عادي. تأخذ دالة runBlocking CoroutineContext وكتلة suspend، وتعيد نتيجة من نوع T.

public fun <T> runBlocking(
    context: CoroutineContext = EmptyCoroutineContext,
    block: suspend CoroutineScope.() -> T
): T

runBlocking تشغل event-loop جديداً على الخيط الحالي. عندما تستدعي الكوروتين دالة suspend (مثل delay() أو await())، runBlocking تحجر الخيط وتنفذ كوروتينات أخرى مجدولة على نفس الخيط حتى تستؤنف المعلقة. هذا هو الحجز التعاوني — الخيط ليس خاملاً بل يعالج كوروتينات أخرى.

كيف يعمل runBlocking

تعتمد آلية runBlocking الداخلية على event-loop: عند استدعاء دالة suspend، توقف runBlocking تنفيذ الكتلة الحالية وتشغل كوروتينات أخرى من الطابور. عندما تكتمل دالة suspend، يستؤنف التنفيذ. يستمر هذا الدورة حتى تنتهي جميع الكوروتينات.

Event-loop تحت الغطاء

runBlocking تستخدم مجموعة خيوط أحادية خاصة بها لتنفيذ الكوروتينات. بخلاف Dispatchers.IO أو Default، runBlocking لا تبدل الخيوط — بل تعالج جميع الكوروتينات على الخيط الحالي، متداولة تنفيذها. هذا هو المنشئ الوحيد الذي يضمن التنفيذ على نفس الخيط.

fun main() {
    val threadName = Thread.currentThread().getName()
    println("قبل runBlocking على $threadName")

    val result = runBlocking {
        println("داخل runBlocking على ${Thread.currentThread().getName()}")
        delay(500L)
        "Done"
    }

    println("بعد runBlocking: $result")
}

سيظهر الإخراج أن جميع الأوامر println الثلاثة تتنفذ على نفس الخيط. runBlocking لا تبدل الخيوط بل تنظم تعدد مهام تعاونياً داخل خيط واحد باستخدام event-loop.

متى استخدام runBlocking

runBlocking مبررة في ثلاثة سيناريوهات: نقطة الدخول main() في تطبيقات واجهة الأوامر، اختبارات الوحدة لدوال suspend والجسر — استدعاء كود suspend من مكتبات قائمة على callbacks أو حاجزة. في كود Android الإنتاجي، استخدامه على الخيط الرئيسي ممنوع بشكل قاطع.

لاختبارات Android، استخدم kotlinx-coroutines-test مع TestDispatcher بدلاً من runBlocking. يوفر ذلك التحكم في الوقت، التنظيف التلقائي وعزل الاختبارات.

بدائل runBlocking

في معظم السيناريوهات، يمكن وينبغي استبدال runBlocking ببدائل غير متزامنة. لـ Android، هذه هي viewModelScope، lifecycleScope أو CoroutineScope مع الموزع المناسب. للاختبارات — TestCoroutineDispatcher و runTest.

    // سيئ: runBlocking على الخيط الرئيسي لـ Android
runBlocking(Dispatchers.Main) {
    val result = networkApi.fetchData()
    textView.setText(result)
}

// جيد: lifecycleScope
lifecycleScope.launch {
    val result = withContext(Dispatchers.IO) { networkApi.fetchData() }
    textView.setText(result)
}

للاختبارات، البديل هو runTest من kotlinx-coroutines-test. ينشئ TestCoroutineScope بوقت افتراضي، مما يسمح باختبار التأخيرات دون انتظار حقيقي. هذا يسرع الاختبارات ويجعلها حتمية.

أمثلة استخدام runBlocking

أكثر السيناريوهات شيوعًا هو اختبار دوال suspend. runBlocking في الاختبارات تسمح بالانتظار المتزامن لنتيجة الكوروتين دون تغيير المعمارية. السيناريو الثاني هو مكتبات بواصلات برمجة API قائمة على callbacks، حيث تستدعى دوال suspend من سياق حاجز عبر runBlocking.

// اختبار دالة suspend باستخدام runBlocking
class RepositoryTest {
    @Test
    fun `fetchUser returns correct data`() {
        val repository = UserRepository(FakeApi())

        val result = runBlocking {
            repository.fetchUser("123")
        }

        assertEquals("John", result.name)
        assertEquals("john@test.com", result.email)
    }
}

للجسر بين callbacks وعالم suspend، استخدم CompletableDeferred مع runBlocking بدلاً من callbacks — هذا يبسط سلاسل العمليات غير المتزامنة ويحسن قراءة الكود.

مخاطر الاستخدام الخاطئ

الاستخدام غير الصحيح لـ runBlocking هو أحد الأخطاء الشائعة عند الانتقال من نهج الحجز إلى الكوروتينات. المشاكل الرئيسية: الاستدعاء على الخيط الرئيسي لـ Android، تداخل runBlocking داخل بعضها البعض، استخدامها داخل دوال غير متزامنة وتشغيل عمليات طويلة عبر runBlocking.

• ANR — runBlocking على الخيط الرئيسي لـ Android تحجر عرض واجهة المستخدم لأكثر من 5 ثوان
• التسيب (إغلاق متبادل) — runBlocking متداخلة داخل كوروتين على نفس الخيط تؤدي إلى الحجز المتبادل
• الخلط بين الموزعات — Dispatchers.Main داخل runBlocking في خيط خلفي ليس له Looper ويرمي استثناء
• تسريب الذاكرة — runBlocking لا تلغى تلقائياً عند إتلاف Activity/Fragment

القاعدة الذهبية: runBlocking هي جسر، ليس بديلاً. استخدمها فقط لربط العوالم الحاجزة وغير الحاجزة. لجميع المهام الأخرى، استخدم launch، async أو lifecycleScope.