عرض مصدر Kotlin/inline functions

<noinclude>{{DISPLAYTITLE:الدوال المباشرة (Inline Functions) في لغة Kotlin}}</noinclude>
== الدوال المباشرة (Inline Functions) ==
ينتُج عن استخدام [[Kotlin/lambdas|الدوال من المرتبة الأعلى (higher-order functions)]] بعض التأثيرات السلبيّة أثناء التنفيذ (runtime)، إذ تُعدُّ كل دالة كائنًا (object) ضمن نطاقٍ مغلقٍ (closure) يشمل المتغيِّرات التي يمكن الوصول إليها في بُنية الدالة، كما ويتطلَّب ذلك تكلفةً إضافيّةً عند تخصيص جزءٍ من الذاكرة (لكلٍ من كائنات الدوال والأصناف [classes]) وعند الاستدعاءات الوهمية (virtual calls) أثناء التنفيذ.

وقد يُحدُّ من هذه المشاكل باللجوء إلى تعابير lambda المباشرة، إذ تُعدُّ الدالة <code>lock()</code>‎ مثالًا جيدًا لمثل هذه الحالات التي تُجعَل فيها lambda مباشرةً في موقع الاستدعاء، مثل:<syntaxhighlight lang="kotlin">
lock(l) { foo() }
</syntaxhighlight>إذ بدلًا من إنشاء كائن الدالة للمعاملات وتوليد الاستدعاء يمكن أن يقوم المٌترجِم (compiler) بالشيفرة الآتية:<syntaxhighlight lang="kotlin">
l.lock()
try {
    foo()
}
finally {
    l.unlock()
}
</syntaxhighlight>حيث يجب تحديد الدالة <code>lock()‎</code> بالمُحدِّد <code>inline</code> كما يلي:<syntaxhighlight lang="kotlin">
inline fun <T> lock(lock: Lock, body: () -> T): T {
    // ...
}
</syntaxhighlight>والذي سيؤثّر على كلٍّ من الدالة -ذاتها- وتعبير lambda المُمرَّر لها، حيث سيُضمَّن كل ذلك مباشرةً في موقع الاستدعاء، وقد تصبح الشيفرة أكثر طولًا، ولكن إن تمّ هذا بطريقةٍ سديدةٍ (بتجنُّب التضمين المباشر للدوال الضخمة) فسيُجدي ذلك في الأداء، وخاصة عند مواقع الاستدعاء في الحلقات (loops).

== المُحدِّد <code>noinline</code> ==
قد نحتاج أحيانًا إلى التضمين المباشر "للبعض" (والبعض فقط) من تعابير lambda (المُمرَّرة إلى الدوال المباشرة)، يُستخدَم المُحدِّد <code>noinline</code> عندئذٍ لتحديد العناصر التي لا تخضع للتضمين المباشر، كما في الشيفرة:<syntaxhighlight lang="kotlin">
inline fun foo(inlined: () -> Unit, noinline notInlined: () -> Unit) {
    // ...
}
</syntaxhighlight>إذ يُسمَح باستدعاء تعابير lambda المباشرة داخل الدوال المباشرة فقط أو بتمريرها كوسيطٍ مباشرٍ، أمّا العناصر المحُدَّدة بالكلمة المفتاحيّة <code>noinline</code> فيمكن أن تُعامَل بأيّة طريقة كانت، كتخزينها في الحقول (fields) أو تمريرها أو ... إلخ.

وتجدر الإشارة إلى أنّ المترجِم سيُعلِم بتحذيرٍ إن احتوت الدالة المباشرة على معاملاتٍ غير مباشرة أو معاملات نوعٍ ليست reified (كما ستُشرَح لاحقًا)، لأنّ ذلك لا يُجدي نفعًا، وبالإمكان تجاوز هذا التحذير -عند الحاجة المُلحَّة للتضمين المباشر- باستخدام التوصيف (annotation) الآتي: ‎<code>@Suppress("NOTHING_TO_INLINE")</code>‎.

== أوامر العودة غير المحليّة (Non-local returns) ==
نستطيع في Kotlin استخدام الأمر <code>return</code> غير المقيّد (unqualified) للخروج من الدالة المُسمّاة (named function) أو الدالة المجهولة (anonymous function)، أمّا للعودة من تعبير lambda يجب استخدام [[Kotlin/returns|التسمية (label)]]، ولا يُسمَح بأمر <code>return</code> مفردًا كما هو داخل التعبير، لأن تعبير lambda غير قادرٍ على العودة من الدالة المحيطة به (enclosing)، مثل:<syntaxhighlight lang="kotlin">
fun foo() {
    ordinaryFunction {
        return // سينتج خطأ: لا يمكن العودة من الدالة هنا
    }
}
</syntaxhighlight>أمّا إن كانت الدالة التي يُمرَّر لها التعبير lambda مباشرةً فيمكن عندئذٍ جعل أمر العودة مباشرًا كذلك، وبالتالي تكون الشيفرة الآتية صحيحةً:<syntaxhighlight lang="kotlin">
fun foo() {
    inlineFunction {
        return // صحيحة لأن التعبير lambda
               // من النوع المباشر
    }
}
</syntaxhighlight>وتُسمّى أوامر الرجوع هذه (والموجودة في تعبير lambda ولكنّها المسؤولة عن العودة من الدالة المحيطة به) بأوامر الرجوع غير المحليّة، وهذا ما تكون عليه عادةً بُنية الحلقات التي تحيط بها الدوال المباشرة، مثل:<syntaxhighlight lang="kotlin">
fun hasZeros(ints: List<Int>): Boolean {
    ints.forEach {
        if (it == 0) return true // العودة من hasZeros
    }
    return false
}
</syntaxhighlight>ويمكن لبعض الدوال المباشرة استدعاء تعابير lambda المُمرَّرة لها كمعاملاتٍ، ولا يتمّ ذلك من بُنية الدالة مباشرةً (directly) وإنمّا من أي سياقٍ تنفيذيّ آخر كالكائن المحلي (local object) أو دالةٍ متداخلةٍ (nested)، ولا يُسمَح حينها بالتحكم بالتدفق غير المحليّ في تعابير lamnda، إذ يجب أن يكون معامل lambda مُحدَّدًا بالكلمة المفتاحيّة <code>crossinline</code> كما في الشيفرة:<syntaxhighlight lang="kotlin">
inline fun f(crossinline body: () -> Unit) {
    val f = object: Runnable {
        override fun run() = body()
    }
    // ...
}
</syntaxhighlight>ملاحظة: إنّ استخدام الأمرين <code>break</code> و <code>continue</code> في دوال lambda المباشرة في Kotlin غير ممكنٍ، وقد يُسمَح بذلك في الإصدارات القادمة.

== المعاملات من النوع <code>reified</code> ==
قد نحتاج أحيانًا للوصول إلى نوعٍ مُمرَّر كمعاملٍ (parameter)، مثل:<syntaxhighlight lang="kotlin">
fun <T> TreeNode.findParentOfType(clazz: Class<T>): T? {
    var p = parent
    while (p != null && !clazz.isInstance(p)) {
        p = p.parent
    }
    @Suppress("UNCHECKED_CAST")
    return p as T?
}
</syntaxhighlight>إذ سيجري عبور الشجرة حيث ستُستخدَم الانعكاسات (reflections) للتحقُّق من النوع في العقد، وسيكون موقع الاستدعاء بالشكل:<syntaxhighlight lang="kotlin">
treeNode.findParentOfType(MyTreeNode::class.java)
</syntaxhighlight>وما نريده فعليًا هو تمرير النوع لهذه الدالة، أي استدعاؤها كما يلي:<syntaxhighlight lang="kotlin">
treeNode.findParentOfType<MyTreeNode>()
</syntaxhighlight>للقيام بذلك تُستخدَم المعاملات من النوع <code>reified</code> ، وتصبح الشيفرة بالشكل:<syntaxhighlight lang="kotlin">
inline fun <reified T> TreeNode.findParentOfType(): T? {
    var p = parent
    while (p != null && p !is T) {
        p = p.parent
    }
    return p as T?
}
</syntaxhighlight>إذ تُقيَّد معاملات النوع بالمُحدِّد <code>reified</code> مما يجعلها متاحةً داخل الدالة وكأنها صنف عاديّ. وبما أن الدالة مباشرةٌ فلا حاجة لأي انعكاس (reflection) هنا، ويُتاح استخدام المعاملات مثل <code>‎!is</code> و<code>as</code> كذلك، كما ويمكن استدعاؤها -كما ذُكر سابقًا- بالصيغة: <code>myTree.findParentOfType<MyTreeNodeType>()</code>‎.

وعلى الرغم من أنه لا حاجة للانعكاسات في كثيرٍ من الحالات، فما يزال استخدامها ممكنًا مع معاملات النوع <code>reified</code> كما يلي:<syntaxhighlight lang="kotlin">
inline fun <reified T> membersOf() = T::class.members

fun main(s: Array<String>) {
    println(membersOf<StringBuilder>().joinToString("\n"))
}
</syntaxhighlight>ولا يمكن أن تحتوي الدوال العادية على معاملاتٍ من النوع <code>reified</code> ؛ لأنه  لا يُسمَح للنوع الذي لا يملك تمثيلًا تنفيذيًا (كالمعامل الذي لا يكون <code>reified</code>  أو النوع الزائف مثل <code>Nothing</code>) أن يكون من النوع <code>reified</code>.

== الخاصّيّات المباشرة (بدءًا من الإصدار 1.1) ==
تُستخدَم الكلمة المفتاحيّة <code>inline</code> للوصول إلى الخاصّيّات التي ليس لها حقولٌ مساعدةٌ (backing fields)، وبالإمكان توصيف عمليات الوصول بشكلٍ منفصلٍ عن بعضهما كما يلي:<syntaxhighlight lang="kotlin">
val foo: Foo
    inline get() = Foo()

var bar: Bar
    get() = ...
    inline set(v) { ... }
</syntaxhighlight>كما ويمكن توصيف الخاصية بمجملها، وهذا يجعل كلًا من <code>get</code> و<code>set</code> مباشرتين:<syntaxhighlight lang="kotlin">
inline var bar: Bar
    get() = ...
    set(v) { ... }
</syntaxhighlight>إذ تُضمّن مباشرةً في موقع الاستدعاء كما لو أنها دالةٌ مباشرةٌ عاديّة.

== التقييدات على الدوال المباشرة في الواجهات العامة (Public API) ==
عندما تكون الدالة المباشرة من النوع <code>public</code> أو <code>protected</code> وليست جزءًا من تصريحٍ من النوع <code>private</code> أو <code>internal</code> فإنها حينئذٍ تُعدُّ واجهةً عامةً للوحدة (module)، وبالتالي فمن الممكن استدعاؤها من أيّ وحدةٍ أخرى، كما ويمكن جعلها مباشرةً في مواقع الاستدعاء، لكنّ هذا سيفرض بعض المخاطر من ناحية عدم التوافق الثنائيّ (binary incompatibility) والذي يحدث نتيجةً لبعض التغييرات في الوحدة التي تصرِّح عن الدالة المباشرة، وذلك إن كان استدعاء الوحدة لا يُترجَم ثانيةً بعد ذلك التغيير.

وللحد من هذه المخاطر لا يُسمح للدوال المباشرة في واجهات API العامّة باستخدام تصريحات الواجهات غير العامّة (non-public-API declarations)، أي لا يُسمح لها بالتصريحات من النوعين <code>private</code> و <code>internal</code> في بُنيتها.

وتُتاح إضافة التوصيف (annotation) بالصيغة ‎<code>@PublishedApi</code> إلى التصريح من النوع <code>internal</code> ، ممّا سيسمح باستخدامه في الدوال المباشرة في الواجهات العامّة، وعند تحديد الدالة المباشرة من النوع <code>internal</code> (عبر التوصيف ‎<code>@PublishedApi</code>) فسيُتحقَّق من بُنيتها وكأنها عامّة (public).

== مصادر<span> </span> ==
* [https://kotlinlang.org/docs/reference/inline-functions.html صفحة الدوال المباشرة في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Function]]
[[تصنيف:Kotlin Lambdas]]
[[تصنيف:Kotlin Retur]]
[[تصنيف:Kotlin Property]]