pthread_cancel(3)

NUME
pthread_cancel - trimite o cerere de anulare către un fir

BIBLIOTECA
Biblioteca de fire de execuție POSIX (libpthread, -lpthread)

SINOPSIS
#include <pthread.h>

int pthread_cancel(pthread_t thread);

DESCRIERE
Funcția pthread_cancel() trimite o cerere de anulare către firul thread. Dacă și când reacționează firul țintă la cererea de anulare depinde de două atribute care se află sub controlul firului respectiv: capacitatea sa de anulare state și type.

Starea de anulare a unui fir, determinată de pthread_setcancelstate(3), poate fi enabled (implicit pentru firele noi) sau disabled. Dacă un fir are anularea dezactivată, atunci o cerere de anulare rămâne în așteptare până când firul activează anularea. Dacă un fir a activat anularea, atunci tipul său de anulare determină momentul în care are loc anularea.

Tipul de anulare a unui fir, determinat de pthread_setcanceltype(3), poate fi fie asincron, fie deferred (implicit pentru firele noi). Anulabilitatea asincronă înseamnă că firul poate fi anulat în orice moment (de obicei imediat, dar sistemul nu garantează acest lucru). Capacitatea de anulare amânată înseamnă că anularea va fi amânată până când firul va apela o funcție care este un punct de anulare. O listă de funcții care sunt sau pot fi puncte de anulare este furnizată în pthreads(7).

Atunci când se dă curs unei cereri de anulare, pentru thread au loc următoarele etape (în această ordine):

(1) Gestionarii de curățare a anulării sunt scoși (în ordinea inversă a ordinii în care au fost introduși) și apelați; (a se vedea pthread_cleanup_push(3).)

(2) Destructorii de date specifici firelor sunt apelați, într-o ordine nespecificată; (a se vedea pthread_key_create(3).)

(3) Firul este terminat; (a se vedea pthread_exit(3)).

Etapele de mai sus au loc în mod asincron în ceea ce privește apelul pthread_cancel(); starea de retur a apelului pthread_cancel() informează doar apelantul dacă cererea de anulare a fost pusă în coadă cu succes.

După terminarea unui fir de execuție anulat, o asociere cu acel fir de execuție folosind pthread_join(3) obține PTHREAD_CANCELED ca stare de ieșire a firului de execuție; (unirea cu un fir este singura modalitate de a ști că anularea s-a încheiat).

VALOAREA RETURNATĂ
În caz de succes, pthread_cancel() returnează 0; în caz de eroare, returnează un număr de eroare diferit de zero.

ERORI-IEȘIRE

ESRCH
    Nu a putut fi găsit niciun fir de execuție cu identificatorul thread.

ATRIBUTE
Pentru o explicație a termenilor folosiți în această secțiune, a se vedea attributes(7).
Interfață | Atribut | Valoare
pthread_cancel() | Siguranța firelor | MT-Safe

VERSIUNI
În Linux, anularea este implementată utilizând semnale. În cadrul implementării threading NPTL, primul semnal în timp real (adică semnalul 32) este utilizat în acest scop. În LinuxThreads, se utilizează al doilea semnal în timp real, dacă sunt disponibile semnale în timp real, altfel se utilizează SIGUSR2.

STANDARDE
POSIX.1-2008.

ISTORIC
glibc 2.0 POSIX.1-2001.

EXEMPLE
Programul de mai jos creează un fir și apoi îl anulează. Firul principal se unește cu firul anulat pentru a verifica dacă starea sa de ieșire a fost PTHREAD_CANCELED. Următoarea sesiune shell arată ce se întâmplă atunci când rulăm programul:

    $ ./a.out
    thread_func(): pornit; anulare dezactivată
    main(): se trimite cererea de anulare
    thread_func(): privind activarea anulării
    main(): firul a fost anulat

  Sursa programului
    #include <errno.h>
    #include <pthread.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <unistd.h>

    #define handle_error_en(en, msg) \
            do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

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

        /* Dezactivează anularea pentru o perioadă, astfel încât
           să nu reacționăm imediat la o cerere de anulare. */

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

        printf("%s(): pornit; anulare dezactivată\n", __func__);
        sleep(5);
        printf("%s(): privind activarea anulării\n", __func__);

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

        /* sleep() este un punct de anulare. */

        sleep(1000);        /* Ar trebui să se anuleze în timp ce dormim */

        /* N-ar trebui să ajungă niciodată aici. */

        printf("%s(): nu este anulat!\n", __func__);
        return NULL;
    }

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

        /* Începe un fir și apoi îi trimite o cerere de anulare. */

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

        sleep(2);           /* Dă firului o șansă de a începe */

        printf("%s(): se trimite cererea de anulare\n", __func__);
        s = pthread_cancel(thr);
        if (s != 0)
            handle_error_en(s, "pthread_cancel");

        /* Se alătură firului pentru a vedea care a fost starea sa de ieșire. */

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

        if (res == PTHREAD_CANCELED)
            printf("%s(): firul a fost anulat\n", __func__);
        else
            printf("%s(): firul nu a fost anulat (nu ar trebui să se întâmple!)\n",
                   __func__);
        exit(EXIT_SUCCESS);
    }

CONSULTAȚI ȘI
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)

TRADUCERE
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>

Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 (https://www.gnu.org/licenses/gpl-3.0.html) sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.

Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.