pthread_cancel(3)

الاسم
pthread_cancel - إرسال طلب إلغاء إلى خيط

المكتبة
مكتبة مسالك POSIX (libpthread، -lpthread)

موجز
#include <pthread.h>

int pthread_cancel(pthread_t thread);

الوصف
ترسل الدالة pthread_cancel() طلب إلغاء إلى الخيط thread. يعتمد ما إذا كان الخيط الهدف يستجيب لطلب الإلغاء ومتى يستجيب على سمتين تحت سيطرة ذلك الخيط: حالة القابلية للإلغاء و نوعها.

حالة قابلية الخيط للإلغاء، المحددة بواسطة pthread_setcancelstate(3)، يمكن أن تكون مُفعّلة (المبدئي للخيوط الجديدة) أو مُعطّلة. إذا عطّل خيط الإلغاء، يبقى طلب الإلغاء في قائمة الانتظار حتى يُفعّل الخيط الإلغاء. إذا فعّل خيط الإلغاء، يحدد نوع قابلية الإلغاء متى يحدث الإلغاء.

نوع إلغاء الخيط، المحدد بواسطة pthread_setcanceltype(3)، يمكن أن يكون إما غير متزامن أو مؤجل (المبدئي للخيوط الجديدة). تعني قابلية الإلغاء غير المتزامنة أنه يمكن إلغاء الخيط في أي وقت (عادةً فورًا، لكن النظام لا يضمن ذلك). تعني قابلية الإلغاء المؤجلة أن الإلغاء سيُؤجل حتى يستدعي الخيط دالة هي نقطة إلغاء. تُقدم قائمة بالدوال التي هي أو قد تكون نقاط إلغاء في pthreads(7).

عند تنفيذ طلب إلغاء، تحدث الخطوات التالية للخيط thread (بهذا الترتيب):

(1) تُفرغ معالجات التنظيف للإلغاء (بترتيب عكسي لترتيب دفعها) وتُستدعى. (انظر pthread_cleanup_push(3).)

(2) تُستدعى مدمرات البيانات الخاصة بالخيط، بترتيب غير محدد. (انظر pthread_key_create(3).)

(3) يُنهى الخيط. (انظر pthread_exit(3).)

تحدث الخطوات أعلاه بشكل غير متزامن بالنسبة لاستدعاء pthread_cancel()؛ يُعلم حالة الإرجاع لـ pthread_cancel() المتصل فقط ما إذا كان طلب الإلغاء قد وُضع في قائمة الانتظار بنجاح.

بعد إنهاء خيط مُلغى، يحصل الانضمام إلى ذلك الخيط باستخدام pthread_join(3) على PTHREAD_CANCELED كحالة خروج الخيط. (الانضمام إلى خيط هو الطريقة الوحيدة لمعرفة أن الإلغاء قد اكتمل.)

قيمة الإرجاع
عند النجاح، تُرجع pthread_cancel() 0؛ عند الخطأ، تُرجع رقم خطأ غير صفري.

الأخطاء

ESRCH
    تعذر العثور على أي خيط بالمعرف thread.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
pthread_cancel() | سلامة الخيوط | MT-Safe

الإصدارات
في لينكس، يُنفذ الإلغاء باستخدام الإشارات. تحت تنفيذ الخيوط NPTL، تُستخدم أول إشارة زمن حقيقي (أي الإشارة 32) لهذا الغرض. في LinuxThreads، تُستخدم ثاني إشارة زمن حقيقي، إذا كانت الإشارات الزمن الحقيقي متاحة، وإلا تُستخدم SIGUSR2.

المعايير
POSIX.1-2008.

التاريخ
glibc 2.0 POSIX.1-2001.

أمثلة
ينشئ البرنامج أدناه خيطًا ثم يلغيه. ينضم الخيط الرئيسي إلى الخيط المُلغى للتحقق من أن حالة خروجه كانت PTHREAD_CANCELED. تُظهر جلسة الصدفة التالية ما يحدث عند تشغيل البرنامج:

    $ ./a.out
    thread_func(): started; cancelation disabled
    main(): sending cancelation request
    thread_func(): about to enable cancelation
    main(): thread was canceled

  مصدر البرنامج
    #include <err.h>
    #include <pthread.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <unistd.h>

    static void *
    thread_func(void *ignored_argument)
    {
        int s;

        /* Disable cancelation for a while, so that we don't
           immediately react to a cancelation request.  */

        s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
        if (s != 0)
            errc(EXIT_FAILURE, s, "pthread_setcancelstate");

        printf("%s(): started; cancelation disabled\n", __func__);
        sleep(5);
        printf("%s(): about to enable cancelation\n", __func__);

        s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
        if (s != 0)
            errc(EXIT_FAILURE, s, "pthread_setcancelstate");

        /* sleep() is a cancelation point.  */

        sleep(1000);        /* Should get canceled while we sleep */

        /* Should never get here.  */

        printf("%s(): not canceled!\n", __func__);
        return NULL;
    }

    int
    main(void)
    {
        pthread_t thr;
        void *res;
        int s;

        /* Start a thread and then send it a cancelation request.  */

        s = pthread_create(&thr, NULL, &thread_func, NULL);
        if (s != 0)
            errc(EXIT_FAILURE, s, "pthread_create");

        sleep(2);           /* Give thread a chance to get started */

        printf("%s(): sending cancelation request\n", __func__);
        s = pthread_cancel(thr);
        if (s != 0)
            errc(EXIT_FAILURE, s, "pthread_cancel");

        /* Join with thread to see what its exit status was.  */

        s = pthread_join(thr, &res);
        if (s != 0)
            errc(EXIT_FAILURE, s, "pthread_join");

        if (res == PTHREAD_CANCELED)
            printf("%s(): thread was canceled\n", __func__);
        else
            printf("%s(): thread wasn't canceled (shouldn't happen!)\n",
                   __func__);
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
pthread_cleanup_push(3), pthread_create(3), pthread_exit(3), pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3), pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)

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

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

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