\hypertarget{group__trigger}{
\section{trigger: Safe external event notification}
\label{group__trigger}\index{trigger: Safe external event notification@{trigger: Safe external event notification}}
}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define \hyperlink{group__trigger_g7d26b2b96773d6691536c3a38e17be88}{trigger\_\-pulled}(IO)~((IO) $\rightarrow$ revents)
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{group__trigger_gb7afaf88cd57889a717c1b3437a82114}{trigger\_\-set} (iopoll\_\-fd $\ast$io, const char $\ast$path)
\item 
void \hyperlink{group__trigger_g082e2543c9bc7d2da426d8b2040651ca}{trigger\_\-pull} (const char $\ast$path)
\end{CompactItemize}


\subsection{Detailed Description}
The {\tt trigger} functions provide a safe mechanism for one program to notify another that an event has happened, using a named pipe.

The traditional UNIX mechanism for doing this has been to use signals. Signals, however, suffer from several problems. First, in order to deliver a signal, the sender needs to determine the PID of the recipient. The process of determining the PID is filled with race conditions leaving the possibility of delivering the signal to the wrong process. On the receiving side, receiving the signal puts the receiver into an execution context where the set of safe system calls is restricted.

By using a named pipe, the trigger mechanism avoids both these problems. First, there are no races in accessing the trigger, and no blocking paths either. Secondly, the receiver waits for an event by polling the file descriptor. Upon receiving an event, the receiver is in the same state as normal.

Such events might include a new message being added to a queue etc. No data is delivered with the event. 

\subsection{Define Documentation}
\hypertarget{group__trigger_g7d26b2b96773d6691536c3a38e17be88}{
\index{trigger@{trigger}!trigger\_\-pulled@{trigger\_\-pulled}}
\index{trigger\_\-pulled@{trigger\_\-pulled}!trigger@{trigger}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define trigger\_\-pulled(IO)~((IO) $\rightarrow$ revents)}}
\label{group__trigger_g7d26b2b96773d6691536c3a38e17be88}


Determine if a trigger has been pulled, after a polling loop indicates activity. 

\subsection{Function Documentation}
\hypertarget{group__trigger_g082e2543c9bc7d2da426d8b2040651ca}{
\index{trigger@{trigger}!trigger\_\-pull@{trigger\_\-pull}}
\index{trigger\_\-pull@{trigger\_\-pull}!trigger@{trigger}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void trigger\_\-pull (const char $\ast$ {\em path})}}
\label{group__trigger_g082e2543c9bc7d2da426d8b2040651ca}


Activate a trigger. \hypertarget{group__trigger_gb7afaf88cd57889a717c1b3437a82114}{
\index{trigger@{trigger}!trigger\_\-set@{trigger\_\-set}}
\index{trigger\_\-set@{trigger\_\-set}!trigger@{trigger}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int trigger\_\-set (iopoll\_\-fd $\ast$ {\em io}, const char $\ast$ {\em path})}}
\label{group__trigger_gb7afaf88cd57889a717c1b3437a82114}


Set up a trigger for polling.

The passed {\tt iopoll\_\-fd} must have at least two slots, as the second slot may be required in the event the OS exhibits the \char`\"{}named pipe bug\char`\"{}. This function must be called every time the trigger is pulled to reset the trigger's state. 