pthread_key_create(3)

الاسم
pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific - إدارة بيانات خاصة بالخيط

موجز
#include <pthread.h>

int pthread_key_create(pthread_key_t *key,
                       typeof(void (void *)) *destr_function;
int pthread_key_delete(pthread_key_t key);
int pthread_setspecific(pthread_key_t key, const void *pointer);
void * pthread_getspecific(pthread_key_t key);

الوصف
غالبًا ما تحتاج البرامج إلى متغيرات عامة أو ثابتة لها قيم مختلفة في خيوط مختلفة. نظرًا لأن الخيوط تشترك في مساحة ذاكرة واحدة، لا يمكن تحقيق ذلك باستخدام المتغيرات العادية. البيانات الخاصة بالخيط هي إجابة خيوط POSIX لهذه الحاجة.

يمتلك كل خيط كتلة ذاكرة خاصة، منطقة البيانات الخاصة بالخيط، أو منطقة TSD للاختصار. تُفهرس هذه المنطقة بمفاتيح TSD. تربط منطقة TSD قيمًا من النوع void * بمفاتيح TSD. مفاتيح TSD مشتركة بين جميع الخيوط، لكن القيمة المرتبطة بمفتاح TSD معين يمكن أن تكون مختلفة في كل خيط.

للتحديد، يمكن عرض مناطق TSD كمصفوفات من المؤشرات void *، ومفاتيح TSD كمؤشرات صحيحة إلى هذه المصفوفات، وقيمة مفتاح TSD كقيمة عنصر المصفوفة المقابل في الخيط المستدعي.

عند إنشاء خيط، تربط منطقة TSD الخاصة به مبدئيًا NULL بجميع المفاتيح.

تخصص pthread_key_create() مفتاح TSD جديد. يُخزَّن المفتاح في الموقع المشار إليه بواسطة key. يوجد حد أقصى قدره PTHREAD_KEYS_MAX على عدد المفاتيح المخصصة في وقت معين. القيمة المرتبطة مبدئيًا بالمفتاح المُعاد هي NULL في جميع الخيوط المنفذة حاليًا.

الوسيطة destr_function، إن لم تكن NULL، تحدد دالة مدمرة مرتبطة بالمفتاح. عندما يُنهى خيط عبر pthread_exit() أو بالإلغاء، تُستدعى destr_function مع وسائط القيمة المرتبطة بالمفتاح في ذلك الخيط. لا تُستدعى destr_function إذا كانت تلك القيمة NULL. الترتيب الذي تُستدعى به الدوال المدمرة عند وقت إنهاء الخيط غير محدد.

قبل استدعاء الدالة المدمرة، تُربط القيمة NULL بالمفتاح في الخيط الحالي. قد تعيد الدالة المدمرة، مع ذلك، ربط قيم غير NULL بذلك المفتاح أو بمفتاح آخر. للتعامل مع هذا، إذا بعد استدعاء جميع المدمرات لجميع القيم غير NULL، بقيت بعض القيم غير NULL مع مدمرات مرتبطة، تُكرر العملية. يوقف تطبيق glibc العملية بعد PTHREAD_DESTRUCTOR_ITERATIONS تكرارات، حتى لو بقيت بعض القيم غير NULL مع مدمرات مرتبطة. قد تكرر التطبيقات الأخرى إلى أجل غير مسمى.

تلغي pthread_key_delete() تخصيص مفتاح TSD. لا تتحقق مما إذا كانت قيم غير NULL مرتبطة بذلك المفتاح في الخيوط المنفذة حاليًا، ولا تستدعي الدالة المدمرة المرتبطة بالمفتاح.

تغير pthread_setspecific() القيمة المرتبطة بـ key في الخيط المستدعي، مخزنة pointer المعطى بدلاً من ذلك.

ترجع pthread_getspecific() القيمة المرتبطة حاليًا بـ key في الخيط المستدعي.

قيمة الإرجاع
ترجع pthread_key_create() و pthread_key_delete() و pthread_setspecific() 0 عند النجاح ورمز خطأ غير صفري عند الفشل. إذا نجحت، تخزن pthread_key_create() المفتاح المخصص حديثًا في الموقع المشار إليه بواسطة وسيطتها key.

ترجع pthread_getspecific() القيمة المرتبطة بـ key عند النجاح، وNULL عند الخطأ.

الأخطاء
ترجع pthread_key_create() رمز الخطأ التالي عند الخطأ:

    EAGAIN
        مفاتيح PTHREAD_KEYS_MAX مخصصة بالفعل.

ترجع pthread_key_delete() و pthread_setspecific() رمز الخطأ التالي عند الخطأ:

    EINVAL
        key ليس مفتاح TSD صالحًا ومخصصًا.

ترجع pthread_getspecific() NULL إذا كان key ليس مفتاح TSD صالحًا ومخصصًا.

انظر أيضًا
pthread_create(3), pthread_exit(3), pthread_testcancel(3).

مثال
يُخصص مقطع الشيفرة التالي مصفوفة خاصة بالخيط من 100 حرف، مع استعادة آلية عند خروج الخيط:

    /* Key for the thread-specific buffer */ static pthread_key_t buffer_key;  /* Once-only initialisation of the key */ static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;  /* Allocate the thread-specific buffer */ void buffer_alloc(void) {   pthread_once(&buffer_key_once, buffer_key_alloc);   pthread_setspecific(buffer_key, malloc(100)); }  /* Return the thread-specific buffer */ char * get_buffer(void) {   return (char *) pthread_getspecific(buffer_key); }  /* Allocate the key */ static void buffer_key_alloc() {   pthread_key_create(&buffer_key, buffer_destroy); }  /* Free the thread-specific buffer */ static void buffer_destroy(void * buf) {   free(buf); }

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.