-\begin{figure}[!htb]
- \footnotesize \centering
- \begin{minipage}[c]{15cm}
- \includestruct{listati/pollfd.h}
- \end{minipage}
- \normalsize
- \caption{La struttura \structd{pollfd}, utilizzata per specificare le
- modalità di controllo di un file descriptor alla funzione \func{poll}.}
- \label{fig:file_pollfd}
-\end{figure}
-
-Le costanti che definiscono i valori relativi ai bit usati nelle maschere
-binarie dei campi \var{events} e \var{revents} sono riportati in
-tab.~\ref{tab:file_pollfd_flags}, insieme al loro significato. Le si sono
-suddivise in tre gruppi, nel primo gruppo si sono indicati i bit utilizzati
-per controllare l'attività in ingresso, nel secondo quelli per l'attività in
-uscita, mentre il terzo gruppo contiene dei valori che vengono utilizzati solo
-nel campo \var{revents} per notificare delle condizioni di errore.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|l|}
- \hline
- \textbf{Flag} & \textbf{Significato} \\
- \hline
- \hline
- \const{POLLIN} & È possibile la lettura.\\
- \const{POLLRDNORM}& Sono disponibili in lettura dati normali.\\
- \const{POLLRDBAND}& Sono disponibili in lettura dati prioritari.\\
- \const{POLLPRI} & È possibile la lettura di \itindex{out-of-band} dati
- urgenti.\\
- \hline
- \const{POLLOUT} & È possibile la scrittura immediata.\\
- \const{POLLWRNORM}& È possibile la scrittura di dati normali.\\
- \const{POLLWRBAND}& È possibile la scrittura di dati prioritari.\\
- \hline
- \const{POLLERR} & C'è una condizione di errore.\\
- \const{POLLHUP} & Si è verificato un hung-up.\\
- \const{POLLNVAL} & Il file descriptor non è aperto.\\
- \hline
- \const{POLLMSG} & Definito per compatibilità con SysV.\\
- \hline
- \end{tabular}
- \caption{Costanti per l'identificazione dei vari bit dei campi
- \var{events} e \var{revents} di \struct{pollfd}.}
- \label{tab:file_pollfd_flags}
-\end{table}
-
-Il valore \const{POLLMSG} non viene utilizzato ed è definito solo per
-compatibilità con l'implementazione di SysV che usa gli
-\textit{stream};\footnote{essi sono una interfaccia specifica di SysV non
- presente in Linux, e non hanno nulla a che fare con i file \textit{stream}
- delle librerie standard del C.} è da questi che derivano i nomi di alcune
-costanti, in quanto per essi sono definite tre classi di dati:
-\textsl{normali}, \textit{prioritari} ed \textit{urgenti}. In Linux la
-distinzione ha senso solo per i dati urgenti \itindex{out-of-band} dei socket
-(vedi sez.~\ref{sec:TCP_urgent_data}), ma su questo e su come \func{poll}
-reagisce alle varie condizioni dei socket torneremo in
-sez.~\ref{sec:TCP_serv_poll}, dove vedremo anche un esempio del suo utilizzo.
-Si tenga conto comunque che le costanti relative ai diversi tipi di dati (come
-\const{POLLRDNORM} e \const{POLLRDBAND}) sono utilizzabili soltanto qualora si
-sia definita la macro \macro{\_XOPEN\_SOURCE}.\footnote{e ci si ricordi di
- farlo sempre in testa al file, definirla soltanto prima di includere
- \file{sys/poll.h} non è sufficiente.}
-
-In caso di successo funzione ritorna restituendo il numero di file (un valore
-positivo) per i quali si è verificata una delle condizioni di attesa richieste
-o per i quali si è verificato un errore (nel qual caso vengono utilizzati i
-valori di tab.~\ref{tab:file_pollfd_flags} esclusivi di \var{revents}). Un
-valore nullo indica che si è raggiunto il timeout, mentre un valore negativo
-indica un errore nella chiamata, il cui codice viene riportato al solito
-tramite \var{errno}.
-
-L'uso di \func{poll} consente di superare alcuni dei problemi illustrati in
-precedenza per \func{select}; anzitutto, dato che in questo caso si usa un
-vettore di strutture \struct{pollfd} di dimensione arbitraria, non esiste il
-limite introdotto dalle dimensioni massime di un \itindex{file~descriptor~set}
-\textit{file descriptor set} e la dimensione dei dati passati al kernel
-dipende solo dal numero dei file descriptor che si vogliono controllare, non
-dal loro valore.\footnote{anche se usando dei bit un \textit{file descriptor
- set} può essere più efficiente di un vettore di strutture \struct{pollfd},
- qualora si debba osservare un solo file descriptor con un valore molto alto
- ci si troverà ad utilizzare inutilmente un maggiore quantitativo di
- memoria.}
-
-Inoltre con \func{select} lo stesso \itindex{file~descriptor~set} \textit{file
- descriptor set} è usato sia in ingresso che in uscita, e questo significa
-che tutte le volte che si vuole ripetere l'operazione occorre reinizializzarlo
-da capo. Questa operazione, che può essere molto onerosa se i file descriptor
-da tenere sotto osservazione sono molti, non è invece necessaria con
-\func{poll}.
-
-Abbiamo visto in sez.~\ref{sec:file_select} come lo standard POSIX preveda una
-variante di \func{select} che consente di gestire correttamente la ricezione
-dei segnali nell'attesa su un file descriptor. Con l'introduzione di una
-implementazione reale di \func{pselect} nel kernel 2.6.16, è stata aggiunta
-anche una analoga funzione che svolga lo stesso ruolo per \func{poll}.
-
-In questo caso si tratta di una estensione che è specifica di Linux e non è
-prevista da nessuno standard; essa può essere utilizzata esclusivamente se si
-definisce la macro \macro{\_GNU\_SOURCE} ed ovviamente non deve essere usata
-se si ha a cuore la portabilità. La funzione è \funcd{ppoll}, ed il suo
-prototipo è:
-\begin{prototype}{sys/poll.h}
- {int ppoll(struct pollfd *fds, nfds\_t nfds, const struct timespec *timeout,
- const sigset\_t *sigmask)}
-
- La funzione attende un cambiamento di stato su un insieme di file
- descriptor.
-
- \bodydesc{La funzione restituisce il numero di file descriptor con attività
- in caso di successo, o 0 se c'è stato un timeout e -1 in caso di errore,
- ed in quest'ultimo caso \var{errno} assumerà uno dei valori:
- \begin{errlist}
- \item[\errcode{EBADF}] si è specificato un file descriptor sbagliato in uno
- degli insiemi.
- \item[\errcode{EINTR}] la funzione è stata interrotta da un segnale.
- \item[\errcode{EINVAL}] il valore di \param{nfds} eccede il limite
- \macro{RLIMIT\_NOFILE}.
- \end{errlist}
- ed inoltre \errval{EFAULT} e \errval{ENOMEM}.}
-\end{prototype}
-
-La funzione ha lo stesso comportamento di \func{poll}, solo che si può
-specificare, con l'argomento \param{sigmask}, il puntatore ad una maschera di
-segnali; questa sarà la maschera utilizzata per tutto il tempo che la funzione
-resterà in attesa, all'uscita viene ripristinata la maschera originale. L'uso
-di questa funzione è cioè equivalente, come illustrato nella pagina di
-manuale, all'esecuzione atomica del seguente codice:
-\includecodesnip{listati/ppoll_means.c}
-
-Eccetto per \param{timeout}, che come per \func{pselect} deve essere un
-puntatore ad una struttura \struct{timespec}, gli altri argomenti comuni con
-\func{poll} hanno lo stesso significato, e la funzione restituisce gli stessi
-risultati illustrati in precedenza.
-
-
-\subsection{L'interfaccia di \textit{epoll}}
-\label{sec:file_epoll}
-
-\itindbeg{epoll}
-
-Nonostante \func{poll} presenti alcuni vantaggi rispetto a \func{select},
-anche questa funzione non è molto efficiente quando deve essere utilizzata con
-un gran numero di file descriptor,\footnote{in casi del genere \func{select}
- viene scartata a priori, perché può avvenire che il numero di file
- descriptor ecceda le dimensioni massime di un \itindex{file~descriptor~set}
- \textit{file descriptor set}.} in particolare nel caso in cui solo pochi di
-questi diventano attivi. Il problema in questo caso è che il tempo impiegato
-da \func{poll} a trasferire i dati da e verso il kernel è proporzionale al
-numero di file descriptor osservati, non a quelli che presentano attività.
-
-Quando ci sono decine di migliaia di file descriptor osservati e migliaia di
-eventi al secondo,\footnote{il caso classico è quello di un server web di un
- sito con molti accessi.} l'uso di \func{poll} comporta la necessità di
-trasferire avanti ed indietro da user space a kernel space la lunga lista
-delle strutture \struct{pollfd} migliaia di volte al secondo. A questo poi si
-aggiunge il fatto che la maggior parte del tempo di esecuzione sarà impegnato
-ad eseguire una scansione su tutti i file descriptor tenuti sotto controllo
-per determinare quali di essi (in genere una piccola percentuale) sono
-diventati attivi. In una situazione come questa l'uso delle funzioni classiche
-dell'interfaccia dell'\textit{I/O multiplexing} viene a costituire un collo di
-bottiglia che degrada irrimediabilmente le prestazioni.
-
-Per risolvere questo tipo di situazioni sono state ideate delle interfacce
-specialistiche\footnote{come \texttt{/dev/poll} in Solaris, o \texttt{kqueue}
- in BSD.} il cui scopo fondamentale è quello di restituire solamente le
-informazioni relative ai file descriptor osservati che presentano una
-attività, evitando così le problematiche appena illustrate. In genere queste
-prevedono che si registrino una sola volta i file descriptor da tenere sotto
-osservazione, e forniscono un meccanismo che notifica quali di questi
-presentano attività.
-
-Le modalità con cui avviene la notifica sono due, la prima è quella classica
-(quella usata da \func{poll} e \func{select}) che viene chiamata \textit{level
- triggered}.\footnote{la nomenclatura è stata introdotta da Jonathan Lemon in
- un articolo su \texttt{kqueue} al BSDCON 2000, e deriva da quella usata
- nell'elettronica digitale.} In questa modalità vengono notificati i file
-descriptor che sono \textsl{pronti} per l'operazione richiesta, e questo
-avviene indipendentemente dalle operazioni che possono essere state fatte su
-di essi a partire dalla precedente notifica. Per chiarire meglio il concetto
-ricorriamo ad un esempio: se su un file descriptor sono diventati disponibili
-in lettura 2000 byte ma dopo la notifica ne sono letti solo 1000 (ed è quindi
-possibile eseguire una ulteriore lettura dei restanti 1000), in modalità
-\textit{level triggered} questo sarà nuovamente notificato come
-\textsl{pronto}.
-
-La seconda modalità, è detta \textit{edge triggered}, e prevede che invece
-vengano notificati solo i file descriptor che hanno subito una transizione da
-\textsl{non pronti} a \textsl{pronti}. Questo significa che in modalità
-\textit{edge triggered} nel caso del precedente esempio il file descriptor
-diventato pronto da cui si sono letti solo 1000 byte non verrà nuovamente
-notificato come pronto, nonostante siano ancora disponibili in lettura 1000
-byte. Solo una volta che si saranno esauriti tutti i byte disponibili, e che
-il file descriptor sia tornato non essere pronto, si potrà ricevere una
-ulteriore notifica qualora ritornasse pronto.
-
-Nel caso di Linux al momento la sola interfaccia che fornisce questo tipo di
-servizio è \textit{epoll},\footnote{l'interfaccia è stata creata da Davide
- Libenzi, ed è stata introdotta per la prima volta nel kernel 2.5.44, ma la
- sua forma definitiva è stata raggiunta nel kernel 2.5.66.} anche se sono in
-discussione altre interfacce con le quali si potranno effettuare lo stesso
-tipo di operazioni;\footnote{al momento della stesura di queste note (Giugno
- 2007) un'altra interfaccia proposta è quella di \textit{kevent}, che
- fornisce un sistema di notifica di eventi generico in grado di fornire le
- stesse funzionalità di \textit{epoll}, esiste però una forte discussione
- intorno a tutto ciò e niente di definito.} \textit{epoll} è in grado di
-operare sia in modalità \textit{level triggered} che \textit{edge triggered}.
-
-La prima versione \textit{epoll} prevedeva l'apertura di uno speciale file di
-dispositivo, \texttt{/dev/epoll}, per ottenere un file descriptor da
-utilizzare con le funzioni dell'interfaccia,\footnote{il backporting
- dell'interfaccia per il kernel 2.4, non ufficiale, utilizza sempre questo
- file.} ma poi si è passati all'uso una apposita \textit{system call}. Il
-primo passo per usare l'interfaccia di \textit{epoll} è pertanto quello di
-chiamare la funzione \funcd{epoll\_create}, il cui prototipo è:
-\begin{prototype}{sys/epoll.h}
- {int epoll\_create(int size)}
-
- Apre un file descriptor per \textit{epoll}.
-
- \bodydesc{La funzione restituisce un file descriptor in caso di successo, o
- $-1$ in caso di errore, nel qual caso \var{errno} assumerà uno dei valori:
- \begin{errlist}
- \item[\errcode{EINVAL}] si è specificato un valore di \param{size} non
- positivo.
- \item[\errcode{ENFILE}] si è raggiunto il massimo di file descriptor aperti
- nel sistema.
- \item[\errcode{ENOMEM}] non c'è sufficiente memoria nel kernel per creare
- l'istanza.
- \end{errlist}
-}
-\end{prototype}
-
-La funzione restituisce un file descriptor speciale,\footnote{esso non è
- associato a nessun file su disco, inoltre a differenza dei normali file
- descriptor non può essere inviato ad un altro processo attraverso un socket
- locale (vedi sez.~\ref{sec:sock_fd_passing}).} detto anche \textit{epoll
- descriptor}, che viene associato alla infrastruttura utilizzata dal kernel
-per gestire la notifica degli eventi; l'argomento \param{size} serve a dare
-l'indicazione del numero di file descriptor che si vorranno tenere sotto
-controllo, ma costituisce solo un suggerimento per semplificare l'allocazione
-di risorse sufficienti, non un valore massimo.
-
-Una volta ottenuto un file descriptor per \textit{epoll} il passo successivo è
-indicare quali file descriptor mettere sotto osservazione e quali operazioni
-controllare, per questo si deve usare la seconda funzione dell'interfaccia,
-\funcd{epoll\_ctl}, il cui prototipo è:
-\begin{prototype}{sys/epoll.h}
- {int epoll\_ctl(int epfd, int op, int fd, struct epoll\_event *event)}
-
- Esegue le operazioni di controllo di \textit{epoll}.
-
- \bodydesc{La funzione restituisce $0$ in caso di successo o $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà uno dei valori:
- \begin{errlist}
- \item[\errcode{EBADF}] il file descriptor \param{epfd} o \param{fd} non sono
- validi.
- \item[\errcode{EEXIST}] l'operazione richiesta è \const{EPOLL\_CTL\_ADD} ma
- \param{fd} è già stato inserito in \param{epfd}.
- \item[\errcode{EINVAL}] il file descriptor \param{epfd} non è stato ottenuto
- con \func{epoll\_create}, o \param{fd} è lo stesso \param{epfd} o
- l'operazione richiesta con \param{op} non è supportata.
- \item[\errcode{ENOENT}] l'operazione richiesta è \const{EPOLL\_CTL\_MOD} o
- \const{EPOLL\_CTL\_DEL} ma \param{fd} non è inserito in \param{epfd}.
- \item[\errcode{ENOMEM}] non c'è sufficiente memoria nel kernel gestire
- l'operazione richiesta.
- \item[\errcode{EPERM}] il file \param{fd} non supporta \textit{epoll}.
- \end{errlist}
-}
-\end{prototype}
-
-Il comportamento della funzione viene controllato dal valore dall'argomento
-\param{op} che consente di specificare quale operazione deve essere eseguita.
-Le costanti che definiscono i valori utilizzabili per \param{op}
-sono riportate in tab.~\ref{tab:epoll_ctl_operation}, assieme al significato
-delle operazioni cui fanno riferimento.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|p{8cm}|}
- \hline
- \textbf{Valore} & \textbf{Significato} \\
- \hline
- \hline
- \const{EPOLL\_CTL\_ADD}& Aggiunge un nuovo file descriptor da osservare
- \param{fd} alla lista dei file descriptor
- controllati tramite \param{epfd}, in
- \param{event} devono essere specificate le
- modalità di osservazione.\\
- \const{EPOLL\_CTL\_MOD}& Modifica le modalità di osservazione del file
- descriptor \param{fd} secondo il contenuto di
- \param{event}.\\
- \const{EPOLL\_CTL\_DEL}& Rimuove il file descriptor \param{fd} dalla lista
- dei file controllati tramite \param{epfd}.\\
- \hline
- \end{tabular}
- \caption{Valori dell'argomento \param{op} che consentono di scegliere quale
- operazione di controllo effettuare con la funzione \func{epoll\_ctl}.}
- \label{tab:epoll_ctl_operation}
-\end{table}
-
-La funzione prende sempre come primo argomento un file descriptor di
-\textit{epoll}, \param{epfd}, che deve essere stato ottenuto in precedenza con
-una chiamata a \func{epoll\_create}. L'argomento \param{fd} indica invece il
-file descriptor che si vuole tenere sotto controllo, quest'ultimo può essere
-un qualunque file descriptor utilizzabile con \func{poll}, ed anche un altro
-file descriptor di \textit{epoll}, ma non lo stesso \param{epfd}.
-
-L'ultimo argomento, \param{event}, deve essere un puntatore ad una struttura
-di tipo \struct{epoll\_event}, ed ha significato solo con le operazioni
-\const{EPOLL\_CTL\_MOD} e \const{EPOLL\_CTL\_ADD}, per le quali serve ad
-indicare quale tipo di evento relativo ad \param{fd} si vuole che sia tenuto
-sotto controllo. L'argomento viene ignorato con l'operazione
-\const{EPOLL\_CTL\_DEL}.\footnote{fino al kernel 2.6.9 era comunque richiesto
- che questo fosse un puntatore valido, anche se poi veniva ignorato, a
- partire dal 2.6.9 si può specificare anche un valore \texttt{NULL}.}
-
-
-
-\begin{figure}[!htb]
- \footnotesize \centering
- \begin{minipage}[c]{15cm}
- \includestruct{listati/epoll_event.h}
- \end{minipage}
- \normalsize
- \caption{La struttura \structd{epoll\_event}, che consente di specificare
- gli eventi associati ad un file descriptor controllato con
- \textit{epoll}.}
- \label{fig:epoll_event}
-\end{figure}
-
-La struttura \struct{epoll\_event} è l'analoga di \struct{pollfd} e come
-quest'ultima serve sia in ingresso (quando usata con \func{epoll\_ctl}) ad
-impostare quali eventi osservare, che in uscita (nei risultati ottenuti con
-\func{epoll\_wait}) per ricevere le notifiche degli eventi avvenuti. La sua
-definizione è riportata in fig.~\ref{fig:epoll_event}.
-
-Il primo campo, \var{events}, è una maschera binaria in cui ciascun bit
-corrisponde o ad un tipo di evento, o una modalità di notifica; detto campo
-deve essere specificato come OR aritmetico delle costanti riportate in
-tab.~\ref{tab:epoll_events}. Il secondo campo, \var{data}, serve ad indicare a
-quale file descriptor si intende fare riferimento, ed in astratto può
-contenere un valore qualsiasi che permetta di identificarlo, di norma comunque
-si usa come valore lo stesso \param{fd}.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|p{8cm}|}
- \hline
- \textbf{Valore} & \textbf{Significato} \\
- \hline
- \hline
- \const{EPOLLIN} & Il file è pronto per le operazioni di lettura
- (analogo di \const{POLLIN}).\\
- \const{EPOLLOUT} & Il file è pronto per le operazioni di scrittura
- (analogo di \const{POLLOUT}).\\
- \const{EPOLLRDHUP} & L'altro capo di un socket di tipo
- \const{SOCK\_STREAM} (vedi sez.~\ref{sec:sock_type})
- ha chiuso la connessione o il capo in scrittura
- della stessa (vedi sez.~\ref{sec:TCP_shutdown}).\\
- \const{EPOLLPRI} & Ci sono \itindex{out-of-band} dati urgenti
- disponibili in lettura (analogo di
- \const{POLLPRI}); questa condizione viene comunque
- riportata in uscita, e non è necessaria impostarla
- in ingresso.\\
- \const{EPOLLERR} & Si è verificata una condizione di errore
- (analogo di \const{POLLERR}); questa condizione
- viene comunque riportata in uscita, e non è
- necessaria impostarla in ingresso.\\
- \const{EPOLLHUP} & Si è verificata una condizione di hung-up.\\
- \const{EPOLLET} & Imposta la notifica in modalità \textit{edge
- triggered} per il file descriptor associato.\\
- \const{EPOLLONESHOT}& Imposta la modalità \textit{one-shot} per il file
- descriptor associato.\footnotemark\\
- \hline
- \end{tabular}
- \caption{Costanti che identificano i bit del campo \param{events} di
- \struct{epoll\_event}.}
- \label{tab:epoll_events}
-\end{table}
-
-\footnotetext{questa modalità è disponibile solo a partire dal kernel 2.6.2.}
-
-Le modalità di utilizzo di \textit{epoll} prevedano che si definisca qual'è
-l'insieme dei file descriptor da tenere sotto controllo tramite un certo
-\textit{epoll descriptor} \param{epfd} attraverso una serie di chiamate a
-\const{EPOLL\_CTL\_ADD}.\footnote{un difetto dell'interfaccia è che queste
- chiamate devono essere ripetute per ciascun file descriptor, incorrendo in
- una perdita di prestazioni qualora il numero di file descriptor sia molto
- grande; per questo è stato proposto di introdurre come estensione una
- funzione \func{epoll\_ctlv} che consenta di effettuare con una sola chiamata
- le impostazioni per un blocco di file descriptor.} L'uso di
-\const{EPOLL\_CTL\_MOD} consente in seguito di modificare le modalità di
-osservazione di un file descriptor che sia già stato aggiunto alla lista di
-osservazione.
-
-Le impostazioni di default prevedono che la notifica degli eventi richiesti
-sia effettuata in modalità \textit{level triggered}, a meno che sul file
-descriptor non si sia impostata la modalità \textit{edge triggered},
-registrandolo con \const{EPOLLET} attivo nel campo \var{events}. Si tenga
-presente che è possibile tenere sotto osservazione uno stesso file descriptor
-su due \textit{epoll descriptor} diversi, ed entrambi riceveranno le
-notifiche, anche se questa pratica è sconsigliata.
-
-Qualora non si abbia più interesse nell'osservazione di un file descriptor lo
-si può rimuovere dalla lista associata a \param{epfd} con
-\const{EPOLL\_CTL\_DEL}; si tenga conto inoltre che i file descriptor sotto
-osservazione che vengono chiusi sono eliminati dalla lista automaticamente e
-non è necessario usare \const{EPOLL\_CTL\_DEL}.
-
-Infine una particolare modalità di notifica è quella impostata con
-\const{EPOLLONESHOT}: a causa dell'implementazione di \textit{epoll} infatti
-quando si è in modalità \textit{edge triggered} l'arrivo in rapida successione
-di dati in blocchi separati\footnote{questo è tipico con i socket di rete, in
- quanto i dati arrivano a pacchetti.} può causare una generazione di eventi
-(ad esempio segnalazioni di dati in lettura disponibili) anche se la
-condizione è già stata rilevata.\footnote{si avrebbe cioè una rottura della
- logica \textit{edge triggered}.}
-
-Anche se la situazione è facile da gestire, la si può evitare utilizzando
-\const{EPOLLONESHOT} per impostare la modalità \textit{one-shot}, in cui la
-notifica di un evento viene effettuata una sola volta, dopo di che il file
-descriptor osservato, pur restando nella lista di osservazione, viene
-automaticamente disattivato,\footnote{la cosa avviene contestualmente al
- ritorno di \func{epoll\_wait} a causa dell'evento in questione.} e per
-essere riutilizzato dovrà essere riabilitato esplicitamente con una successiva
-chiamata con \const{EPOLL\_CTL\_MOD}.
-
-Una volta impostato l'insieme di file descriptor che si vogliono osservare con
-i relativi eventi, la funzione che consente di attendere l'occorrenza di uno
-di tali eventi è \funcd{epoll\_wait}, il cui prototipo è:
-\begin{prototype}{sys/epoll.h}
- {int epoll\_wait(int epfd, struct epoll\_event * events, int maxevents, int
- timeout)}
-
- Attende che uno dei file descriptor osservati sia pronto.
-
- \bodydesc{La funzione restituisce il numero di file descriptor pronti in
- caso di successo o $-1$ in caso di errore, nel qual caso \var{errno}
- assumerà uno dei valori:
- \begin{errlist}
- \item[\errcode{EBADF}] il file descriptor \param{epfd} non è valido.
- \item[\errcode{EFAULT}] il puntatore \param{events} non è valido.
- \item[\errcode{EINTR}] la funzione è stata interrotta da un segnale prima
- della scadenza di \param{timeout}.
- \item[\errcode{EINVAL}] il file descriptor \param{epfd} non è stato ottenuto
- con \func{epoll\_create}, o \param{maxevents} non è maggiore di zero.
- \end{errlist}
-}
-\end{prototype}
-
-La funzione si blocca in attesa di un evento per i file descriptor registrati
-nella lista di osservazione di \param{epfd} fino ad un tempo massimo
-specificato in millisecondi tramite l'argomento \param{timeout}. Gli eventi
-registrati vengono riportati in un vettore di strutture \struct{epoll\_event}
-(che deve essere stato allocato in precedenza) all'indirizzo indicato
-dall'argomento \param{events}, fino ad un numero massimo di eventi impostato
-con l'argomento \param{maxevents}.
-
-La funzione ritorna il numero di eventi rilevati, o un valore nullo qualora
-sia scaduto il tempo massimo impostato con \param{timeout}. Per quest'ultimo,
-oltre ad un numero di millisecondi, si può utilizzare il valore nullo, che
-indica di non attendere e ritornare immediatamente,\footnote{anche in questo
- caso il valore di ritorno sarà nullo.} o il valore $-1$, che indica
-un'attesa indefinita. L'argomento \param{maxevents} dovrà invece essere sempre
-un intero positivo.
-
-Come accennato la funzione restituisce i suoi risultati nel vettore di
-strutture \struct{epoll\_event} puntato da \param{events}; in tal caso nel
-campo \param{events} di ciascuna di esse saranno attivi i flag relativi agli
-eventi accaduti, mentre nel campo \var{data} sarà restituito il valore che era
-stato impostato per il file descriptor per cui si è verificato l'evento quando
-questo era stato registrato con le operazioni \const{EPOLL\_CTL\_MOD} o
-\const{EPOLL\_CTL\_ADD}, in questo modo il campo \var{data} consente di
-identificare il file descriptor.\footnote{ed è per questo che, come accennato,
- è consuetudine usare per \var{data} il valore del file descriptor stesso.}
-
-Si ricordi che le occasioni per cui \func{epoll\_wait} ritorna dipendono da
-come si è impostata la modalità di osservazione (se \textit{level triggered} o
-\textit{edge triggered}) del singolo file descriptor. L'interfaccia assicura
-che se arrivano più eventi fra due chiamate successive ad \func{epoll\_wait}
-questi vengano combinati. Inoltre qualora su un file descriptor fossero
-presenti eventi non ancora notificati, e si effettuasse una modifica
-dell'osservazione con \const{EPOLL\_CTL\_MOD} questi verrebbero riletti alla
-luce delle modifiche.
-
-Si tenga presente infine che con l'uso della modalità \textit{edge triggered}
-il ritorno di \func{epoll\_wait} indica un file descriptor è pronto e resterà
-tale fintanto che non si sono completamente esaurite le operazioni su di esso.
-Questa condizione viene generalmente rilevata dall'occorrere di un errore di
-\errcode{EAGAIN} al ritorno di una \func{read} o una \func{write},\footnote{è
- opportuno ricordare ancora una volta che l'uso dell'I/O multiplexing
- richiede di operare sui file in modalità non bloccante.} ma questa non è la
-sola modalità possibile, ad esempio la condizione può essere riconosciuta
-anche con il fatto che sono stati restituiti meno dati di quelli richiesti.
-
-Come le precedenti \func{select} e \func{poll}, le funzioni dell'interfaccia
-di \textit{epoll} vengono utilizzate prevalentemente con i server di rete,
-quando si devono tenere sotto osservazione un gran numero di socket; per
-questo motivo rimandiamo di nuovo la trattazione di un esempio concreto a
-quando avremo esaminato in dettaglio le caratteristiche dei socket, in
-particolare si potrà trovare un programma che utilizza questa interfaccia in
-sez.~\ref{sec:TCP_sock_multiplexing}.
-
-
-\itindend{epoll}
-
-
-
-\section{L'accesso \textsl{asincrono} ai file}
-\label{sec:file_asyncronous_access}
-
-Benché l'\textit{I/O multiplexing} sia stata la prima, e sia tutt'ora una fra
-le più diffuse modalità di gestire l'I/O in situazioni complesse in cui si
-debba operare su più file contemporaneamente, esistono altre modalità di
-gestione delle stesse problematiche. In particolare sono importanti in questo
-contesto le modalità di accesso ai file eseguibili in maniera
-\textsl{asincrona}, quelle cioè in cui un processo non deve bloccarsi in
-attesa della disponibilità dell'accesso al file, ma può proseguire
-nell'esecuzione utilizzando invece un meccanismo di notifica asincrono (di
-norma un segnale, ma esistono anche altre interfacce, come \itindex{inotify}
-\textit{inotify}), per essere avvisato della possibilità di eseguire le
-operazioni di I/O volute.
-
-
-\subsection{Il \textit{Signal driven I/O}}
-\label{sec:file_asyncronous_operation}
-
-Abbiamo accennato in sez.~\ref{sec:file_open} che è possibile, attraverso
-l'uso del flag \const{O\_ASYNC},\footnote{l'uso del flag di \const{O\_ASYNC} e
- dei comandi \const{F\_SETOWN} e \const{F\_GETOWN} per \func{fcntl} è
- specifico di Linux e BSD.} aprire un file in modalità asincrona, così come è
-possibile attivare in un secondo tempo questa modalità impostando questo flag
-attraverso l'uso di \func{fcntl} con il comando \const{F\_SETFL} (vedi
-sez.~\ref{sec:file_fcntl}).
-
-In realtà parlare di apertura in modalità asincrona non significa che le
-operazioni di lettura o scrittura del file vengono eseguite in modo asincrono
-(tratteremo questo, che è ciò che più propriamente viene chiamato \textsl{I/O
- asincrono}, in sez.~\ref{sec:file_asyncronous_io}), quanto dell'attivazione
-un meccanismo di notifica asincrona delle variazione dello stato del file
-descriptor aperto in questo modo. Quello che succede in questo caso è che il
-sistema genera un segnale (normalmente \const{SIGIO}, ma è possibile usarne
-altri con il comando \const{F\_SETSIG} di \func{fcntl}) tutte le volte che
-diventa possibile leggere o scrivere dal file descriptor che si è posto in
-questa modalità.\footnote{questa modalità non è utilizzabile con i file
- ordinari ma solo con socket, file di terminale o pseudo terminale, e, a
- partire dal kernel 2.6, anche per fifo e pipe.}
-
-Si può inoltre selezionare, con il comando \const{F\_SETOWN} di \func{fcntl},
-quale processo (o gruppo di processi) riceverà il segnale. Se pertanto si
-effettuano le operazioni di I/O in risposta alla ricezione del segnale non ci
-sarà più la necessità di restare bloccati in attesa della disponibilità di
-accesso ai file.
-
-Per questo motivo Stevens, ed anche le pagine di manuale di
-Linux, chiamano questa modalità ``\textit{Signal driven I/O}''. Questa è
-ancora un'altra modalità di gestione dell'I/O, alternativa all'uso di
-\itindex{epoll} \textit{epoll},\footnote{anche se le prestazioni ottenute con
- questa tecnica sono inferiori, il vantaggio è che questa modalità è
- utilizzabile anche con kernel che non supportano \textit{epoll}, come quelli
- della serie 2.4, ottenendo comunque prestazioni superiori a quelle che si
- hanno con \func{poll} e \func{select}.} che consente di evitare l'uso delle
-funzioni \func{poll} o \func{select} che, come illustrato in
-sez.~\ref{sec:file_epoll}, quando vengono usate con un numero molto grande di
-file descriptor, non hanno buone prestazioni.
-
-Tuttavia con l'implementazione classica dei segnali questa modalità di I/O
-presenta notevoli problemi, dato che non è possibile determinare, quando i
-file descriptor sono più di uno, qual è quello responsabile dell'emissione del
-segnale. Inoltre dato che i segnali normali non si accodano (si ricordi quanto
-illustrato in sez.~\ref{sec:sig_notification}), in presenza di più file
-descriptor attivi contemporaneamente, più segnali emessi nello stesso momento
-verrebbero notificati una volta sola.
-
-Linux però supporta le estensioni POSIX.1b dei segnali real-time, che vengono
-accodati e che permettono di riconoscere il file descriptor che li ha emessi.
-In questo caso infatti si può fare ricorso alle informazioni aggiuntive
-restituite attraverso la struttura \struct{siginfo\_t}, utilizzando la forma
-estesa \var{sa\_sigaction} del gestore installata con il flag
-\const{SA\_SIGINFO} (si riveda quanto illustrato in
-sez.~\ref{sec:sig_sigaction}).
-
-Per far questo però occorre utilizzare le funzionalità dei segnali real-time
-(vedi sez.~\ref{sec:sig_real_time}) impostando esplicitamente con il comando
-\const{F\_SETSIG} di \func{fcntl} un segnale real-time da inviare in caso di
-I/O asincrono (il segnale predefinito è \const{SIGIO}). In questo caso il
-gestore, tutte le volte che riceverà \const{SI\_SIGIO} come valore del
-campo \var{si\_code}\footnote{il valore resta \const{SI\_SIGIO} qualunque sia
- il segnale che si è associato all'I/O asincrono, ed indica appunto che il
- segnale è stato generato a causa di attività nell'I/O asincrono.} di
-\struct{siginfo\_t}, troverà nel campo \var{si\_fd} il valore del file
-descriptor che ha generato il segnale.
-
-Un secondo vantaggio dell'uso dei segnali real-time è che essendo questi
-ultimi dotati di una coda di consegna ogni segnale sarà associato ad uno solo
-file descriptor; inoltre sarà possibile stabilire delle priorità nella
-risposta a seconda del segnale usato, dato che i segnali real-time supportano
-anche questa funzionalità. In questo modo si può identificare immediatamente
-un file su cui l'accesso è diventato possibile evitando completamente l'uso di
-funzioni come \func{poll} e \func{select}, almeno fintanto che non si satura
-la coda.
-
-Se infatti si eccedono le dimensioni di quest'ultima, il kernel, non potendo
-più assicurare il comportamento corretto per un segnale real-time, invierà al
-suo posto un solo \const{SIGIO}, su cui si saranno accumulati tutti i segnali
-in eccesso, e si dovrà allora determinare con un ciclo quali sono i file
-diventati attivi. L'unico modo per essere sicuri che questo non avvenga è di
-impostare la lunghezza della coda dei segnali real-time ad una dimensione
-identica al valore massimo del numero di file descriptor
-utilizzabili.\footnote{vale a dire impostare il contenuto di
- \procfile{/proc/sys/kernel/rtsig-max} allo stesso valore del contenuto di
- \procfile{/proc/sys/fs/file-max}.}
-
-% TODO fare esempio che usa O_ASYNC
-
-
-\subsection{I meccanismi di notifica asincrona.}
-\label{sec:file_asyncronous_lease}
-
-Una delle domande più frequenti nella programmazione in ambiente unix-like è
-quella di come fare a sapere quando un file viene modificato. La
-risposta\footnote{o meglio la non risposta, tanto che questa nelle Unix FAQ
- \cite{UnixFAQ} viene anche chiamata una \textit{Frequently Unanswered
- Question}.} è che nell'architettura classica di Unix questo non è
-possibile. Al contrario di altri sistemi operativi infatti un kernel unix-like
-classico non prevedeva alcun meccanismo per cui un processo possa essere
-\textsl{notificato} di eventuali modifiche avvenute su un file. Questo è il
-motivo per cui i demoni devono essere \textsl{avvisati} in qualche
-modo\footnote{in genere questo vien fatto inviandogli un segnale di
- \const{SIGHUP} che, per una convenzione adottata dalla gran parte di detti
- programmi, causa la rilettura della configurazione.} se il loro file di
-configurazione è stato modificato, perché possano rileggerlo e riconoscere le
-modifiche.
-
-Questa scelta è stata fatta perché provvedere un simile meccanismo a livello
-generico per qualunque file comporterebbe un notevole aumento di complessità
-dell'architettura della gestione dei file, il tutto per fornire una
-funzionalità che serve soltanto in alcuni casi particolari. Dato che
-all'origine di Unix i soli programmi che potevano avere una tale esigenza
-erano i demoni, attenendosi a uno dei criteri base della progettazione, che
-era di far fare al kernel solo le operazioni strettamente necessarie e
-lasciare tutto il resto a processi in user space, non era stata prevista
-nessuna funzionalità di notifica.
-
-Visto però il crescente interesse nei confronti di una funzionalità di questo
-tipo, che è molto richiesta specialmente nello sviluppo dei programmi ad
-interfaccia grafica, quando si deve presentare all'utente lo stato del
-filesystem, sono state successivamente introdotte delle estensioni che
-permettessero la creazione di meccanismi di notifica più efficienti dell'unica
-soluzione disponibile con l'interfaccia tradizionale, che è quella del
-\itindex{polling} \textit{polling}.
-
-Queste nuove funzionalità sono delle estensioni specifiche, non
-standardizzate, che sono disponibili soltanto su Linux (anche se altri kernel
-supportano meccanismi simili). Alcune di esse sono realizzate, e solo a
-partire dalla versione 2.4 del kernel, attraverso l'uso di alcuni
-\textsl{comandi} aggiuntivi per la funzione \func{fcntl} (vedi
-sez.~\ref{sec:file_fcntl}), che divengono disponibili soltanto se si è
-definita la macro \macro{\_GNU\_SOURCE} prima di includere \file{fcntl.h}.
-
-\index{file!lease|(}
-
-La prima di queste funzionalità è quella del cosiddetto \textit{file lease};
-questo è un meccanismo che consente ad un processo, detto \textit{lease
- holder}, di essere notificato quando un altro processo, chiamato a sua volta
-\textit{lease breaker}, cerca di eseguire una \func{open} o una
-\func{truncate} sul file del quale l'\textit{holder} detiene il
-\textit{lease}.
-
-La notifica avviene in maniera analoga a come illustrato in precedenza per
-l'uso di \const{O\_ASYNC}: di default viene inviato al \textit{lease holder}
-il segnale \const{SIGIO}, ma questo segnale può essere modificato usando il
-comando \const{F\_SETSIG} di \func{fcntl}.\footnote{anche in questo caso si
- può rispecificare lo stesso \const{SIGIO}.} Se si è fatto questo\footnote{è
- in genere è opportuno farlo, come in precedenza, per utilizzare segnali
- real-time.} e si è installato il gestore del segnale con \const{SA\_SIGINFO}
-si riceverà nel campo \var{si\_fd} della struttura \struct{siginfo\_t} il
-valore del file descriptor del file sul quale è stato compiuto l'accesso; in
-questo modo un processo può mantenere anche più di un \textit{file lease}.
-
-Esistono due tipi di \textit{file lease}: di lettura (\textit{read lease}) e
-di scrittura (\textit{write lease}). Nel primo caso la notifica avviene quando
-un altro processo esegue l'apertura del file in scrittura o usa
-\func{truncate} per troncarlo. Nel secondo caso la notifica avviene anche se
-il file viene aperto il lettura; in quest'ultimo caso però il \textit{lease}
-può essere ottenuto solo se nessun altro processo ha aperto lo stesso file.
-
-Come accennato in sez.~\ref{sec:file_fcntl} il comando di \func{fcntl} che
-consente di acquisire un \textit{file lease} è \const{F\_SETLEASE}, che viene
-utilizzato anche per rilasciarlo. In tal caso il file descriptor \param{fd}
-passato a \func{fcntl} servirà come riferimento per il file su cui si vuole
-operare, mentre per indicare il tipo di operazione (acquisizione o rilascio)
-occorrerà specificare come valore dell'argomento \param{arg} di \func{fcntl}
-uno dei tre valori di tab.~\ref{tab:file_lease_fctnl}.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|l|}
- \hline
- \textbf{Valore} & \textbf{Significato} \\
- \hline
- \hline
- \const{F\_RDLCK} & Richiede un \textit{read lease}.\\
- \const{F\_WRLCK} & Richiede un \textit{write lease}.\\
- \const{F\_UNLCK} & Rilascia un \textit{file lease}.\\
- \hline
- \end{tabular}
- \caption{Costanti per i tre possibili valori dell'argomento \param{arg} di
- \func{fcntl} quando usata con i comandi \const{F\_SETLEASE} e
- \const{F\_GETLEASE}.}
- \label{tab:file_lease_fctnl}
-\end{table}
-
-Se invece si vuole conoscere lo stato di eventuali \textit{file lease}
-occorrerà chiamare \func{fcntl} sul relativo file descriptor \param{fd} con il
-comando \const{F\_GETLEASE}, e si otterrà indietro nell'argomento \param{arg}
-uno dei valori di tab.~\ref{tab:file_lease_fctnl}, che indicheranno la
-presenza del rispettivo tipo di \textit{lease}, o, nel caso di
-\const{F\_UNLCK}, l'assenza di qualunque \textit{file lease}.
-
-Si tenga presente che un processo può mantenere solo un tipo di \textit{lease}
-su un file, e che un \textit{lease} può essere ottenuto solo su file di dati
-(pipe e dispositivi sono quindi esclusi). Inoltre un processo non privilegiato
-può ottenere un \textit{lease} soltanto per un file appartenente ad un
-\acr{uid} corrispondente a quello del processo. Soltanto un processo con
-privilegi di amministratore (cioè con la \itindex{capabilities} capability
-\const{CAP\_LEASE}, vedi sez.~\ref{sec:proc_capabilities}) può acquisire
-\textit{lease} su qualunque file.
-
-Se su un file è presente un \textit{lease} quando il \textit{lease breaker}