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
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,
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}
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}
\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}
projects / gapil.git / commitdiff