epoll_wait(2)

NUME
epoll_wait, epoll_pwait, epoll_pwait2 - așteaptă un eveniment de In/Ieș pe un descriptor de fișier epoll

BIBLIOTECA
Biblioteca C standard (libc, -lc)

SINOPSIS
#include <sys/epoll.h>

int epoll_wait(int n;
               int epfd, struct epoll_event events[n], int n,
               int timeout);
int epoll_pwait(int n;
               int epfd, struct epoll_event events[n], int n,
               int timeout,
               const sigset_t *_Nullable sigmask);
int epoll_pwait2(int n;
               int epfd, struct epoll_event events[n], int n,
               const struct timespec *_Nullable timeout,
               const sigset_t *_Nullable sigmask);

DESCRIERE
Apelul de sistem epoll_wait() așteaptă evenimente pe instanța epoll(7) menționată de descriptorul de fișier epfd. Tamponul indicat de events este utilizat pentru a returna informații din lista pregătită despre descriptorii de fișiere din lista de interese care au unele evenimente disponibile. Până la n sunt returnate de epoll_wait(). Argumentul n trebuie să fie mai mare decât zero.

Argumentul timeout specifică numărul de milisecunde în care epoll_wait() se va bloca. Timpul este măsurat în raport cu ceasul CLOCK_MONOTONIC.

Un apel la epoll_wait() se va bloca până când:

•   un descriptor de fișier furnizează un eveniment;

•   apelul este întrerupt de un gestionar de semnal; sau

•   timpul de așteptare expiră.

Rețineți că intervalul timeout va fi rotunjit la gradul de finețe al ceasului de sistem, iar întârzierile de planificare ale nucleului înseamnă că intervalul de blocare poate fi depășit cu o cantitate mică. Specificarea unui timeout de -1 face ca epoll_wait() să se blocheze indefinit, în timp ce specificarea unui timeout egal cu zero face ca epoll_wait() să returneze imediat, chiar dacă nu sunt disponibile evenimente.

structura epoll_event este descrisă în epoll_event(3type).

Câmpul data al fiecărei structuri epoll_event returnate conține aceleași date ca cele specificate în cel mai recent apel la epoll_ctl(2) (EPOLL_CTL_ADD, EPOLL_CTL_MOD) pentru descriptorul de fișier deschis corespunzător.

Câmpul events este o mască de biți care indică evenimentele care au avut loc pentru descrierea fișierului deschis corespunzător. Consultați epoll_ctl(2) pentru o listă a biților care pot apărea în această mască.

  epoll_pwait()
Relația dintre epoll_wait() și epoll_pwait() este analogă cu relația dintre select(2) și pselect(2): la fel ca pselect(2), epoll_pwait() permite unei aplicații să aștepte în siguranță până când un descriptor de fișier devine gata sau până când un semnal este recepționat.

Următorul apel epoll_pwait():

    ready = epoll_pwait(epfd, &events, n, timeout, &sigmask);

este echivalent cu executarea atomică a următoarelor apeluri:

    sigset_t origmask;

    pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
    ready = epoll_wait(epfd, &events, n, timeout);
    pthread_sigmask(SIG_SETMASK, &origmask, NULL);

Argumentul sigmask poate fi specificat ca NULL, caz în care epoll_pwait() este echivalent cu epoll_wait().

  epoll_pwait2()
Apelul de sistem epoll_pwait2() este echivalent cu epoll_pwait(), cu excepția argumentului timeout. Acesta ia un argument de tip timespec pentru a putea specifica timpul de așteptare pentru rezoluția de nanosecunde. Acest argument funcționează la fel ca în pselect(2) și ppoll(2). Dacă timeout este NULL, atunci epoll_pwait2() se poate bloca indefinit.

VALOAREA RETURNATĂ
În caz de succes, epoll_wait() returnează numărul de descriptori de fișier pregătiți pentru operația I/O solicitată sau zero dacă niciun descriptor de fișier nu a devenit pregătit în timpul milisecundelor timeout solicitate. În caz de eșec, epoll_wait() returnează -1 și errno este configurată pentru a indica eroarea.

ERORI-IEȘIRE

EBADF
    epfd nu este un descriptor de fișier valid.

EFAULT
    Zona de memorie indicată de events nu este accesibilă cu permisiuni de scriere.

EINTR
    Apelul a fost întrerupt de un gestionar de semnal înainte ca (1) oricare dintre evenimentele solicitate să se producă sau (2) timpul de așteptare să expire; a se vedea signal(7).

EINVAL
    epfd nu este un descriptor de fișier epoll sau n este mai mic sau egal cu zero.

STANDARDE
Linux.

ISTORIC

epoll_wait()
    Linux 2.6, glibc 2.3.2.

epoll_pwait()
    Linux 2.6.19, glibc 2.6.

epoll_pwait2()
    Linux 5.11.

NOTE
În timp ce un fir este blocat într-un apel la epoll_wait(), este posibil ca un alt fir să adauge un descriptor de fișier la instanța epoll aflată în așteptare. Dacă noul descriptor de fișier devine disponibil, acesta va determina deblocarea apelului epoll_wait().

Dacă mai mult de n descriptori de fișiere sunt disponibili atunci când se apelează epoll_wait(), atunci apelurile succesive epoll_wait() vor parcurge în cerc setul de descriptori de fișiere disponibili. Acest comportament ajută la evitarea scenariilor de înfometare, în care un proces nu observă că alți descriptori de fișiere sunt gata deoarece se concentrează pe un set de descriptori de fișiere despre care se știe deja că sunt pregătiți.

Rețineți că este posibil să apelați epoll_wait() pe o instanță epoll a cărei listă de interese este în prezent goală (sau a cărei listă de interese devine goală deoarece descriptorii de fișiere sunt închiși sau eliminați din interes într-un alt fir). Apelul se va bloca până când un descriptor de fișier este adăugat ulterior la lista de interese (într-un alt fir de execuție) și acel descriptor de fișier devine disponibil.

  Diferențe între biblioteca C și nucleu
Apelurile de sistem brute epoll_pwait() și epoll_pwait2() au un al șaselea argument, size_t sigsetsize, care specifică dimensiunea în octeți a argumentului sigmask. Funcția de învăluire a glibc epoll_pwait() specifică acest argument ca o valoare fixă (egală cu sizeof(sigset_t)).

ERORI
Înainte de Linux 2.6.37, o valoare timeout mai mare decât aproximativ LONG_MAX / HZ milisecunde este tratată ca -1 (adică infinit). Astfel, de exemplu, pe un sistem în care sizeof(long) este 4 și valoarea HZ a nucleului este 1000, aceasta înseamnă că timpii de așteptare mai mari de 35,79 minute sunt tratați ca infinit.

CONSULTAȚI ȘI
epoll_create(2), epoll_ctl(2), epoll(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.