runBlocking — این چیست، پل بلوک‌کننده و چگونه کار می‌کند

runBlocking چیست؟

runBlocking — تابعی در Kotlin است که یک CoroutineScope جدید ایجاد کرده و کوروتین ارسال شده را اجرا می‌کند، رشته جاری را تا تکمیل کامل آن مسدود می‌کند. برخلاف تمام Coroutine Builderهای دیگر، 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 رشته‌ها را تغییر نمی‌دهد — همه کوروتین‌ها را در رشته جاری پردازش می‌کند و اجرای آنها را میان‌اندازی می‌کند. این تنها builderای است که اجرا در همان رشته را تضمین می‌کند.

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 از کتابخانه‌های مبتنی بر callback یا مسدودکننده. در کد تولیدی اندروید استفاده در رشته اصلی قطعاً ممنوع است.

برای تست‌های اندروید به جای runBlocking از kotlinx-coroutines-test با TestDispatcher استفاده کنید. این امکان کنترل زمان، بازنشانی خودکار و ایزوله‌سازی تست‌ها را فراهم می‌کند.

جایگزین‌های runBlocking

در بیشتر سناریوها runBlocking را می‌توان و باید با جایگزین‌های ناهمگام عوض کرد. برای اندروید اینها عبارتند از viewModelScope، lifecycleScope یا CoroutineScope با dispatcher مناسب. برای تست‌ها — TestCoroutineDispatcher و runTest.

    // بد: runBlocking روی رشته اصلی اندروید
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 در تست‌ها امکان انتظار同步 برای نتیجه کوروتین بدون تغییر معماری را فراهم می‌کند. سناریوی دوم — کتابخانه‌هایی با callback API، جایی که توابع 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)
    }
}

برای پل زدن بین دنیای callback و suspend به جای callbackها از CompletableDeferred در ترکیب با runBlocking استفاده کنید — این کار زنجیره عملیات ناهمگام را ساده کرده و خوانایی کد را افزایش می‌دهد.

خطرات استفاده نادرست

استفاده نادرست از runBlocking یکی از اشتباهات رایج هنگام انتقال از رویکرد مسدودکننده به کوروتین‌هاست. مشکلات اصلی: فراخوانی در Main-Thread اندروید، تودرتو کردن runBlocking، استفاده درون توابع ناهمگام و اجرای عملیات طولانی از طریق runBlocking.

• ANR — runBlocking در Main-Thread اندروید رندر UI را بیش از ۵ ثانیه مسدود می‌کند
• Deadlock — runBlocking تودرتو درون کوروتین در همان رشته منجر به بن‌بست متقابل می‌شود
• سردرگمی با dispatcherها — Dispatchers.Main درون runBlocking در رشته پس‌زمینه Looper ندارد و با خطا مواجه می‌شود
• نشت حافظه — runBlocking هنگام نابودی Activity/Fragment به طور خودکار لغو نمی‌شود

قاعده طلایی: runBlocking یک پل است، نه جایگزین. فقط برای اتصال دنیای مسدودکننده و غیرمسدودکننده از آن استفاده کنید. برای همه وظایف دیگر از launch، async یا lifecycleScope استفاده کنید.