# التكامل القابل لإعادة الاستخدام مع C

[English](guide.en.md) · [دليل HTTP](../http/guide.ar.md)

## تواقيع عادية غير آمنة

يستدعي [ordinary.aspl](../examples/c-interop/ar/ordinary.aspl) دالة libc
`abs` بتوقيع ص32 إلى ص32 و`strlen` بنسخة نص C ونتيجة ط64 للحجم.
تحافظ [النسخة الإنجليزية](../examples/c-interop/en/ordinary.aspl) على أسماء
المستخدم والمكتبة والرمز والنصوص نفسها.

```sh
aspl check docs/examples/c-interop/ar/ordinary.aspl
aspl run docs/examples/c-interop/ar/ordinary.aspl
aspl build -o build/http-guide/ordinary docs/examples/c-interop/ar/ordinary.aspl
./build/http-guide/ordinary
```

أنشئ مجلد الناتج أولا واختر 0.5.0 وABI Linux x86-64 System V المدعوم.
يستنتج الوسم السياقي `سي` / `c` التوقيع الدقيق من أنواع المصدر. ضع
`غير_آمن` / `unsafe` على التصريح وعلى كل استدعاء. تقبل التواقيع العامة
0..32 معاملا أصليا. يقابل منطقي C bool ذا بايت واحد، وتحافظ الأعداد الموقعة
وغير الموقعة والعائمة على عرضها. مؤشر_سي مؤشر معتم قابل لعدم وغير مملوك،
ووحدة في النتيجة تعني C void. في هذا الهدف char موقع وshort بحجم 16 بت
وint بحجم 32 وlong وlong long والمؤشر وsize_t بحجم 64. اختر النوع الحقيقي
لـtypedef أو enum. لا استنتاج ABI من الرمز أو الترويسة ولا تحويل عددي ضمني
أو تحويل errno إلى نتيجة أو معاملات متغيرة أو مجاميع بالقيمة أو long double
أو complex أو مؤشرات دوال.

ينشئ `نص_سي(text)` / `cstring(text)` نسخة منتهية بـNUL طول الاستدعاء.
وجود NUL في النص يسبب فخا قبل دخول C. لا يحتفظ C بالمؤشر.
يبقى المحولان `سي_صحيح__مؤشر_محرف_ثابت` / `c_int__const_char_ptr` و
`سي_مزدوج__مزدوج` / `c_double__double` بتحويلاتهما السابقة، نص إلى ص64
وع64 إلى ع64. لا تنطبق تحويلاتهما على التواقيع العامة.

يحمّل وقت التشغيل المكتبات الحرفية الدقيقة بـRTLD_NOW | RTLD_LOCAL ويحل
كل رمز في مكتبتِه قبل البداية، بما فيه التصريحات غير المستخدمة. يفشل غياب
الاعتماديات قبل آثار المصدر. لا يحمّلها `check` أو `build`. على الكاتب
مطابقة التوقيع الحقيقي وصحة المؤشر وسلوك C. الاستدعاءات العادية متزامنة
وقد تحجب التنفيذ، وتستبعد عبر كل مسارات معالجات HTTP والاستدعاءات المدارة.

## مخزن منسوخ ومالك أصلي مشترك

استورد `أساسي::سي` أو `core::c`. تتاح البادئة المكتوبة فقط. الأعضاء
`مخزن` / `Buffer`، و`أنشئ_مخزن` / `buffer`، و`أنشئ_مخزن_صفري` / `zero_buffer`،
و`سعة` / `capacity`، و`انسخ_بايتات` / `bytes`، و`أغلق` / `close`.

| الدالة | التوقيع |
| --- | --- |
| أنشئ_مخزن | `(قائمة<ط8>) -> نتيجة<مخزن>` |
| أنشئ_مخزن_صفري | `(ط64) -> نتيجة<مخزن>` |
| سعة | `(مخزن) -> نتيجة<ط64>` |
| انسخ_بايتات | `(مخزن, ط64) -> نتيجة<قائمة<ط8>>` |
| أغلق | `(مخزن) -> نتيجة<وحدة>` |

ينشئ [buffer.لبات](../examples/c-interop/ar/buffer.لبات) البايتات `00 FF 41`
ويغيّر القائمة الأصلية وينسخ البايتات خارجه ثم يستدعي `memset` من libc
بمدى إخراج صريح. تبقى قائمة المصدر والبايتات المستخرجة مستقلتين.
تثبت [النسخة الإنجليزية](../examples/c-interop/en/buffer.لبات) القواعد نفسها.

```sh
aspl check docs/examples/c-interop/ar/buffer.لبات
aspl run docs/examples/c-interop/ar/buffer.لبات
aspl check docs/examples/c-interop/en/buffer.لبات
aspl run docs/examples/c-interop/en/buffer.لبات
```

تحدد `إدخال(buffer,count)` / `input` و`إخراج` / `output` و
`إدخال_وإخراج` / `inout` مدى بايتات. العدد معامل ص64 أو ط64 أو قيمة حرفية
غير سالبة ضمن السعة، ولا تضيف البيانات الوصفية معاملات C.
يصفر الإخراج المدى المحدد قبل الدخول ويحافظ الإدخال والإخراج على قيمه.
لا تتراجع البايتات عند نتيجة C سالبة. للمدى الفارغ مؤشر sentinel صالح.
يسبب العدد السيئ أو المخزن المغلق أو تداخل نسخ قابلة للكتابة فخا قبل C،
وتقبل نسخ القراءة فقط. لا يثبت هذا التزام C بالسعة.

تحتفظ نسخ المخزن بمالك أصلي واحد ولا تنسخ الحالة الأصلية القابلة للتغيير.
إغلاق نسخة يبطل الجميع وتكرار الإغلاق آمن. يفحص المثال
`foreign.invalid_argument` للاستخراج الكبير و`foreign.closed` لقراءة السعة
بعد إغلاق نسخة. قد يرفض القبول بالرمز `foreign.resource_limit`، ولا يجعل
استدعاء C العادي قابلا للاسترداد. يحتفظ الوصول الأصلي الجاري بالتخزين
المحاسب حتى السكون. تحرر نهاية المراجع والتنفيذ المالكين، بما فيه دورات
الملكية غير القابلة للوصول. لا تحويل إلى عنوان خام يكشف تخزين المالك المدار.

## الاستدعاءات الراجعة المدارة والمراجعة

تحتاج العملية المدارة إلى ربط مراجع في كتالوج الأداة بقبول ومحاسبة وإلغاء
وتنظيف محدودين. لا يسجلها تصريح C أو ادعاء أمان في المصدر. لا ABI عامة
لتثبيت روابط مدارة مستقلة. يقدم كتالوج الإنتاج واجهة HTTP الموردة حاليا.
العرض القابل لإعادة الاستخدام التالي خاص بالمساهمين وبكتالوج الاختبار،
وترفضه أداة الإنتاج عمدا.

يستخدم [managed.aspl](../examples/c-interop/ar/managed.aspl) و
[نظيره الإنجليزي](../examples/c-interop/en/managed.aspl) الوصف الدقيق
`core::managed_fixture` باللغتين. لا تسميات عربية لوصف الاختبار وأعضائه.
الدالة `respond` على المستوى الأعلى بتوقيع
`دالة(Data, قائمة<ط8>) -> قائمة<ط8>` مع نسخة بيانات صريحة.
تتلقى القيمتين 7 و9 وتملأ طابور الأحداث المحدود وتفحص `foreign.overloaded`
ثم تغلق المالك وتفحص `foreign.closed`.

```sh
make build/aspl-managed-test
build/aspl-managed-test check docs/examples/c-interop/ar/managed.aspl
build/aspl-managed-test run docs/examples/c-interop/ar/managed.aspl
build/aspl-managed-test check docs/examples/c-interop/en/managed.aspl
build/aspl-managed-test run docs/examples/c-interop/en/managed.aspl
```

استخدمه في نسخة للمساهمين فقط. يحتفظ التسجيل بهدف وبيانات محددة النوع
دون التقاط أو مؤشر دالة خام. بيانات التسجيل المستقل قابلة للتخزين ولا تحتوي Context فعليا في أي عمق.
يجوز أن تحتوي أوصاف دوال عادية مع خضوعها لتحليل أمان كل مسارات الاستدعاء،
ولا يعبر تمثيلها إلى C. عند تخزين التسجيل في إعدادات HTTP أو حالته، تضيف
قواعد C/S استبعاد قيم الدوال المكشوفة في كل عمق من بيانات التسجيل.
تشترك المقابض في المالك الأصلي.
ينسخ الدخول الأصلي الأحداث إلى طابور محدود ولا يدخل الآلة تكراريا أو من
خيط أصلي. تنفذ الاستدعاءات متسلسلة ولا تتوقف إلا عبر عمليات مدارة مقبولة.
حدود الاختبار 64 مالكا وتسجيلًا وحدثا منتظرا، و32 استدعاء فعالا، و4096
بايت للحدث أو الرد، و30000 ms للحدث، و1000 ms للتنظيف.
مجال مدد C المدارة المراجعة 1..86400000 ms، بينما أدنى تنظيف HTTP هو 1000 ms.

ترفض أجيال التسجيل والمالك الأحداث القديمة ويكتمل الرد مرة واحدة.
يلغي إلغاء التسجيل القبول وينتظر السكون الأصلي ثم يحرر البيانات والتخزين.
يبطل إغلاق نسخة الوصول إلى المالك المشترك. تستخدم الإخفاقات المتوقعة
`foreign.invalid_argument` و`foreign.closed` و`foreign.resource_limit`
و`foreign.overloaded` و`foreign.timeout` و`foreign.cancelled` و
`foreign.host_failure`. لا يعد إلغاء الأب بنتيجة فاشلة للاستدعاء الملغى.
العودة الفورية إلى C بقيمة يحسبها ASPL مستبعدة. يرفض قبل الجمود استدعاء
أصلي متزامن يحتاج إلى انتظار تنفيذ ASPL المحجوب حاليا. لا تكتسب الاستدعاءات
العادية غير الآمنة هذه الصلاحيات.

شغل `make test-http-documentation` لفحص اللغتين ورفض الإنتاج للاختبار
والتنفيذ المباشر والمولد دون مصدر. يحتفظ `make test-native-foreign test-managed`
بفحوص التواقيع والمالكين والطوابير والأجيال والتنظيف الأوسع.