Quasi finite le funzioni dei timer.
authorSimone Piccardi <piccardi@gnulinux.it>
Sat, 24 Jul 2010 16:57:40 +0000 (16:57 +0000)
committerSimone Piccardi <piccardi@gnulinux.it>
Sat, 24 Jul 2010 16:57:40 +0000 (16:57 +0000)
signal.tex

index 6f93285db420917f7da41547b7e784f96e488935..e4aaa11b885a5d043919f6297923911f806d2c29 100644 (file)
@@ -2865,7 +2865,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
-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
@@ -3229,22 +3229,28 @@ 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
-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
-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
-  \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.
 
 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 +3270,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
-\textit{thread}. 
+\textit{thread} di notifica
 
 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}
 
@@ -3276,9 +3282,74 @@ fuzione  \funcd{timer\_getoverrun}, il cui prototipo 
   
   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}
+restituita al gestore del segnale installato con \func{sigaction}, in questo
+modo non è più necessario eseguire successivamente una chiamata a questa
+funzione.
+
+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.
+  \item[\errcode{EFAULT}] si è specificato un indirizzo non valido
+    per \param{curr\_value}.
+  \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, eseguendo
+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}
@@ -3286,9 +3357,10 @@ fuzione  \funcd{timer\_getoverrun}, il cui prototipo 
 \end{functions}
 
 
+% TODO trattare i Posix timer, e le funzioni:
+% timer_delete
+
 
-% 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}