Finiti per la trattazione i timer posix.

[gapil.git] / signal.tex

diff --git a/signal.tex b/signal.tex
index 6f93285db420917f7da41547b7e784f96e488935..addf4f0be7d183cab130f151cad31f02320bb95a 100644 (file)
--- a/signal.tex
+++ b/signal.tex
@@ -1988,7 +1988,9 @@ rispettivamente lo stato di uscita, l'\textit{user time} e il \textit{system
 \var{si\_addr} con l'indirizzo in cui è avvenuto l'errore, \const{SIGIO} (vedi
 sez.~\ref{sec:file_asyncronous_io}) avvalora \var{si\_fd} con il numero del
 file descriptor e \var{si\_band} per i \itindex{out-of-band} dati urgenti
 \var{si\_addr} con l'indirizzo in cui è avvenuto l'errore, \const{SIGIO} (vedi
 sez.~\ref{sec:file_asyncronous_io}) avvalora \var{si\_fd} con il numero del
 file descriptor e \var{si\_band} per i \itindex{out-of-band} dati urgenti

-(vedi sez.~\ref{sec:TCP_urgent_data}) su un socket.
+(vedi sez.~\ref{sec:TCP_urgent_data}) su un socket, il segnale inviato alla
+scadenza di un timer POSIX (vedi sez.~\ref{sec:sig_timer_adv}) avvalora i
+campi \var{si\_timerid} e \var{si\_overrun}.

 
 Benché sia possibile usare nello stesso programma sia \func{sigaction} che
 \func{signal} occorre molta attenzione, in quanto le due funzioni possono
 
 Benché sia possibile usare nello stesso programma sia \func{sigaction} che
 \func{signal} occorre molta attenzione, in quanto le due funzioni possono


@@ -2865,7 +2867,7 @@ tab.~\ref{tab:sig_timer_clockid_types}.
 Per poter utilizzare queste funzionalità le \acr{glibc} richiedono che la
 macro \macro{\_POSIX\_C\_SOURCE} sia definita ad un valore maggiore o uguale
 di \texttt{199309L} (vedi sez.~\ref{sec:intro_gcc_glibc_std}), inoltre i
 Per poter utilizzare queste funzionalità le \acr{glibc} richiedono che la
 macro \macro{\_POSIX\_C\_SOURCE} sia definita ad un valore maggiore o uguale
 di \texttt{199309L} (vedi sez.~\ref{sec:intro_gcc_glibc_std}), inoltre i

-programmi che le usano devono essere linkati con la libreria delle estensioni
+programmi che le usano devono essere collegati con la libreria delle estensioni

 \textit{real-time} usando esplicitamente l'opzione \texttt{-lrt}. Si tenga
 presente inoltre che la disponibilità di queste funzionalità avanzate può
 essere controllato dalla definizione della macro \macro{\_POSIX\_TIMERS} ad un
 \textit{real-time} usando esplicitamente l'opzione \texttt{-lrt}. Si tenga
 presente inoltre che la disponibilità di queste funzionalità avanzate può
 essere controllato dalla definizione della macro \macro{\_POSIX\_TIMERS} ad un


@@ -3179,7 +3181,7 @@ segnale \textit{real-time} per ciascun timer che viene creato con
 \func{timer\_create}; dato che ciascuno di essi richiede un posto nella coda
 dei segnali \textit{real-time}, il numero massimo di timer utilizzabili da un
 processo è limitato dalle dimensioni di detta coda, ed anche, qualora questo
 \func{timer\_create}; dato che ciascuno di essi richiede un posto nella coda
 dei segnali \textit{real-time}, il numero massimo di timer utilizzabili da un
 processo è limitato dalle dimensioni di detta coda, ed anche, qualora questo

-sia stato impostato, dal limite \const{RLIMIT\_SIGPENDING}
+sia stato impostato, dal limite \const{RLIMIT\_SIGPENDING}.

 
 Una volta creato il timer \func{timer\_create} ed ottenuto il relativo
 identificatore, si può attivare o disattivare un allarme (in gergo
 
 Una volta creato il timer \func{timer\_create} ed ottenuto il relativo
 identificatore, si può attivare o disattivare un allarme (in gergo


@@ -3229,22 +3231,29 @@ Ciascuno dei due campi di \struct{itimerspec} indica un tempo, da specificare
 con una precisione fino al nanosecondo tramite una struttura \struct{timespec}
 (la cui definizione è riportata fig.~\ref{fig:sys_timespec_struct}). Il campo
 \var{it\_value} indica la prima scadenza dell'allarme. Di default, quando il
 con una precisione fino al nanosecondo tramite una struttura \struct{timespec}
 (la cui definizione è riportata fig.~\ref{fig:sys_timespec_struct}). Il campo
 \var{it\_value} indica la prima scadenza dell'allarme. Di default, quando il

-valore di \param{flag} è nullo, questo valore viene considerato come un
+valore di \param{flags} è nullo, questo valore viene considerato come un

 intervallo relativo al tempo corrente,\footnote{il primo allarme scatterà cioè
   dopo il numero di secondi e nanosecondi indicati da questo campo.} se invece
 intervallo relativo al tempo corrente,\footnote{il primo allarme scatterà cioè
   dopo il numero di secondi e nanosecondi indicati da questo campo.} se invece

-si usa per \param{flag} il valore \const{TIMER\_ABSTIME}, \var{it\_value}
-viene considerato come valore assoluto rispetto al valore dell'orologio a cui
-è associato il timer.\footnote{quindi a seconda dell'orologio che si usa, si
-  può indicare sia un tempo assoluto, se si opera rispetto all'orologio di
+si usa per \param{flags} il valore \const{TIMER\_ABSTIME},\footnote{al momento
+  questo è l'unico valore valido per \param{flags}.} \var{it\_value} viene
+considerato come un valore assoluto rispetto al valore usato dall'orologio a
+cui è associato il timer.\footnote{quindi a seconda dei casi lo si potrà
+  indicare o come un tempo assoluto, quando si opera rispetto all'orologio di

   sistema (nel qual caso il valore deve essere in secondi e nanosecondi dalla
   sistema (nel qual caso il valore deve essere in secondi e nanosecondi dalla

-  \textit{epoch}) o come un certo numero di secondi o nanosecondi rispetto
-  alla partenza di un orologio di CPU.}
-
-Il campo \var{it\_interval} consente invece di impostare un allarme periodico.
-Se il suo valore è nullo (se cioè sono nulli tutti e due i valori di detta
-struttura \struct{timespec}) l'allarme scatterà una sola volta secondo quando
-indicato con \var{it\_value}, altrimenti il valore specificato verrà preso
-come l'estensione del periodo di ripetizione della generazione dell'allarme.
+  \textit{epoch}) o come numero di secondi o nanosecondi rispetto alla
+  partenza di un orologio di CPU, quando si opera su uno di questi.}  Infine
+un valore nullo di \var{it\_value}\footnote{per nullo si intende con valori
+  nulli per entrambi i i campi \var{tv\_sec} e \var{tv\_nsec}.} può essere
+utilizzato, indipendentemente dal tipo di orologio utilizzato, per disarmare
+l'allarme.
+
+Il campo \var{it\_interval} di \struct{itimerspec} viene invece utilizzato per
+impostare un allarme periodico.  Se il suo valore è nullo (se cioè sono nulli
+tutti e due i valori di detta struttura \struct{timespec}) l'allarme scatterà
+una sola volta secondo quando indicato con \var{it\_value}, altrimenti il
+valore specificato verrà preso come l'estensione del periodo di ripetizione
+della generazione dell'allarme, che proseguirà indefinitamente fintanto che
+non si disarmi il timer.

 
 Se il timer era già stato armato la funzione sovrascrive la precedente
 impostazione, se invece si indica come prima scadenza un tempo già passato,
 
 Se il timer era già stato armato la funzione sovrascrive la precedente
 impostazione, se invece si indica come prima scadenza un tempo già passato,


@@ -3264,11 +3273,11 @@ in coda un solo segnale per timer,\footnote{questo indipendentemente che si
   la coda.}  e se il sistema è sotto carico o se il segnale è bloccato, prima
 della sua ricezione può passare un intervallo di tempo sufficientemente lungo
 ad avere scadenze multiple, e lo stesso può accadere anche se si usa un
   la coda.}  e se il sistema è sotto carico o se il segnale è bloccato, prima
 della sua ricezione può passare un intervallo di tempo sufficientemente lungo
 ad avere scadenze multiple, e lo stesso può accadere anche se si usa un

-\textit{thread}. 
+\textit{thread} di notifica. 

 
 Per questo motivo il gestore del segnale o il \textit{thread} di notifica può
 
 Per questo motivo il gestore del segnale o il \textit{thread} di notifica può

-ottenere una indicazione di quante volte il time è scaduto utilizzando la
-fuzione  \funcd{timer\_getoverrun}, il cui prototipo è:
+ottenere una indicazione di quante volte il timer è scaduto dall'invio della
+notifica utilizzando la funzione \funcd{timer\_getoverrun}, il cui prototipo è:

 \begin{functions}
   \headdecl{time.h}
 
 \begin{functions}
   \headdecl{time.h}
 


@@ -3276,19 +3285,88 @@ fuzione  \funcd{timer\_getoverrun}, il cui prototipo 
   
   Ottiene il numero di scadenze di un timer POSIX.
   
   
   Ottiene il numero di scadenze di un timer POSIX.
   

-  \bodydesc{La funzione restituisce il numero di scadenze di un timer (anche 0
-    se non ve ne sono) in caso di successo e $-1$ in caso di errore, nel qual
-    caso \var{errno} assumerà il valore:
+  \bodydesc{La funzione restituisce il numero di scadenze di un timer in caso
+    di successo e $-1$ in caso di errore, nel qual caso \var{errno} assumerà
+    il valore:
+  \begin{errlist}
+  \item[\errcode{EINVAL}] \param{timerid} non indica un timer valido.
+  \end{errlist}
+}
+\end{functions}
+
+La funzione ritorna il numero delle scadenze avvenute, che può anche essere
+nullo se non ve ne sono state. Come estensione specifica di Linux,\footnote{in
+  realtà lo standard POSIX.1-2001 prevede gli \textit{overrun} solo per i
+  segnali e non ne parla affatto in riferimento ai \textit{thread}.}  quando
+si usa un segnale come meccanismo di notifica, si può ottenere direttamente
+questo valore nel campo \var{si\_overrun} della struttura \struct{siginfo\_t}
+(illustrata in fig.~\ref{fig:sig_siginfo_t}) restituita al gestore del segnale
+installato con \func{sigaction}; in questo modo non è più necessario eseguire
+successivamente una chiamata a questa funzione per ottenere il numero delle
+scadenze. Al gestore del segnale viene anche restituito, come ulteriore
+informazione, l'identificativo del timer, in questo caso nel campo
+\var{si\_timerid}.
+
+Qualora si voglia rileggere lo stato corrente di un timer, ed ottenere il
+tempo mancante ad una sua eventuale scadenza, si deve utilizzare la funzione
+\funcd{timer\_gettime}, il cui prototipo è:
+\begin{functions}
+  \headdecl{time.h}
+
+  \funcdecl{int timer\_gettime(timer\_t timerid, int flags, struct
+    itimerspec *curr\_value)}
+  
+  Legge lo stato di un timer POSIX.
+  
+  \bodydesc{La funzione restituisce 0 in caso di successo e $-1$ in caso di
+    errore, nel qual caso \var{errno} assumerà uno dei seguenti valori:

   \begin{errlist}
   \item[\errcode{EINVAL}] \param{timerid} non indica un timer valido.
   \begin{errlist}
   \item[\errcode{EINVAL}] \param{timerid} non indica un timer valido.

+  \item[\errcode{EFAULT}] si è specificato un indirizzo non valido
+    per \param{curr\_value}.

   \end{errlist}
 }
 \end{functions}
 
   \end{errlist}
 }
 \end{functions}
 

+La funzione restituisce nella struttura \struct{itimerspec} puntata
+da \param{curr\_value} il tempo restante alla prossima scadenza nel campo
+\var{it\_value}. Questo tempo viene sempre indicato in forma relativa, anche
+nei casi in cui il timer era stato precedentemente impostato con
+\const{TIMER\_ABSTIME} indicando un tempo assoluto.  Il ritorno di un valore
+nullo nel campo \var{it\_value} significa che il timer è disarmato o è
+definitivamente scaduto. 
+
+Nel campo \var{it\_interval} di \param{curr\_value} viene invece restituito,
+se questo era stato impostato, il periodo di ripetizione del timer.  Anche in
+questo caso il ritorno di un valore nullo significa che il timer non era stato
+impostato per una ripetizione e doveva operare, come suol dirsi, a colpo
+singolo (in gergo \textit{one shot}).
+
+Infine, quando un timer non viene più utilizzato, lo si può cancellare,
+rimuovendolo dal sistema e recuperando le relative risorse, effettuando in
+sostanza l'operazione inversa rispetto a \funcd{timer\_create}. Per questo
+compito lo standard prevede una apposita funzione \funcd{timer\_delete}, il
+cui prototipo è:
+\begin{functions}
+  \headdecl{time.h}
+
+  \funcdecl{int timer\_delete(timer\_t timerid)}
+  
+  Cancella un timer POSIX.
+  
+  \bodydesc{La funzione restituisce 0 in caso di successo e $-1$ in caso di
+    errore, nel qual caso \var{errno} assumerà uno dei seguenti valori:
+    \begin{errlist}
+    \item[\errcode{EINVAL}] \param{timerid} non indica un timer valido.
+    \end{errlist}
+}
+\end{functions}

 
 

+La funzione elimina il timer identificato da \param{timerid}, disarmandolo se
+questo era stato attivato. Nel caso poco probabile, ma comunque possibile, che
+un timer venga cancellato prima della ricezione del segnale pendente per la
+notifica di una scadenza, il comportamento del sistema è indefinito. 

 
 

-% TODO trattare i Posix timer, e le fuzioni:
-% timer_getoverrun, timer_gettime, timer_settime, timer_create, timer_delete

 
 
 \subsection{Le interfacce per la notifica attraverso i file descriptor}
 
 
 \subsection{Le interfacce per la notifica attraverso i file descriptor}


@@ -3371,7 +3449,7 @@ eventi generici) basato direttamente sull'uso di file descriptor.
 % LocalWords:  resolution CONFIG RES patch REALTIME MONOTONIC RAW NTP CPUTIME
 % LocalWords:  tick calendar The Epoch list getcpuclockid capability CAP getres
 % LocalWords:  ENOSYS pthread ENOENT NULL attribute itimerspec new old ABSTIME
 % LocalWords:  resolution CONFIG RES patch REALTIME MONOTONIC RAW NTP CPUTIME
 % LocalWords:  tick calendar The Epoch list getcpuclockid capability CAP getres
 % LocalWords:  ENOSYS pthread ENOENT NULL attribute itimerspec new old ABSTIME

-% LocalWords:  epoch multiplexing
+% LocalWords:  epoch multiplexing overrun

 
 
 %%% Local Variables: 
 
 
 %%% Local Variables: