-%% fileadv.tex
+gb%% fileadv.tex
%%
%% Copyright (C) 2000-2007 Simone Piccardi. Permission is granted to
%% copy, distribute and/or modify this document under the terms of the GNU Free
}
\end{prototype}
-La funzione restituisce un file descriptor speciale, detto anche \textit{epoll
- descriptor} che viene associato alla infrastruttura utilizzata dal kernel
+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
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 l'argomento \param{op}
+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|l|}
+ \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}.\\
- \const{EPOLL\_CTL\_MOD}& .\\
- \const{EPOLL\_CTL\_DEL}& .\\
+ 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
\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
+\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 anche un valore \texttt{NULL}.}
\begin{figure}[!htb]
\footnotesize \centering
\includestruct{listati/epoll_event.h}
\end{minipage}
\normalsize
- \caption{La struttura \structd{epoll\_event}, .}
- \label{fig:}
+ \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|l|}
+ \begin{tabular}[c]{|l|p{8cm}|}
\hline
\textbf{Valore} & \textbf{Significato} \\
\hline
\hline
- \const{EPOLLIN}& .\\
- \const{EPOLLOUT}& .\\
- \const{EPOLLRDHUP}& .\\
- \const{EPOLLPRI}& .\\
- \const{EPOLLERR}& .\\
- \const{EPOLLHUP}& .\\
- \const{EPOLLET}& .\\
- \const{EPOLLONESHOT}& .\\
+ \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{Valori 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.}
-, da
-specificare con le costanti riportate in tab.,
-La funzione prende come primo argomento un file descriptor di \textit{epoll}
-\param{epfd}, che deve essere stato ottenuto tramite \func{epoll\_create}, e
-consente di impostare le operazioni di osservazione su un altro file
-descriptor \param{fd}
-
-
+Le modalità di utilizzo di \textit{epoll} prevedano che si definisca un
+insieme di file descriptor da tenere sotto controllo su un \textit{epoll
+ descriptor} \param{epfd} con una serie di chiamate a
+\const{EPOLL\_CTL\_ADD}. Il default prevede la notifica in modalità
+\textit{level triggered}, a meno che sul file descriptor non si sia impostata
+la modalità \textit{edge triggered} con \const{EPOLLET}. Si tenga presente
+che è possibile tenere sotto osservazione uno stesso file descriptor su due
+\textit{epoll descriptor} diversi, ed entrambi riceveranno le notifiche, ma la
+pratica è sconsigliata.
+Una particolare modalità di notifica è quella impostata con
+\const{EPOLLONESHOT}: quando si è in modalità \textit{edge triggered} l'arrivo
+in rapida successione di dati in blocchi separati causa la generazione di una
+serie di eventi multipli; in questo caso si può utilizzare la modalità
+\textit{one-shot} in cui la notifica viene effettuata solo la prima volta,
+dopo di che il file descriptor osservato, pur restando nella lista di
+\param{epfd}, viene disattivato, e per essere riutilizzato dovrà essere
+riabilitato con una successiva chiamata con \const{EPOLL\_CTL\_MOD}.
-La funzione esegue l'operazione di controllo specificata dall'argomento
-\param{op},
+Infine qualora un file descriptor posto sotto osservazione dovesse essere
+chiuso, esso sarà automaticamente eliminato dall'insieme dei file descriptor
+osservati.
-\param{fd} alla lista dei file descriptor osservati
-sull'\textit{epoll descripter} \param{epfd}
La funzione che consente di attendere è \funcd{epoll\_wait}, il cui prototipo