From 92670baeed9596c995f85dfaac25f5b1bf62c79c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ji=C5=99=C3=AD=20Sitera?= Date: Thu, 12 Feb 2009 15:26:57 +0000 Subject: [PATCH] Last TODO removed, Operator CHANGED, timeout clarification. --- org.glite.lb.doc/src/notification_api.tex | 70 +++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 13 deletions(-) diff --git a/org.glite.lb.doc/src/notification_api.tex b/org.glite.lb.doc/src/notification_api.tex index 97cb3bb..cb2f851 100644 --- a/org.glite.lb.doc/src/notification_api.tex +++ b/org.glite.lb.doc/src/notification_api.tex @@ -63,24 +63,24 @@ funcions. notification the same encoding of conditions as for the \LB query/response API is used (sec.~\ref{s:queryrec}). - In version 1.x - there is a restriction that at least one particular JobId must be - defined. In \LB 2.0 you cat make a registration based on other - attributes without referencing a particular JobId (you can select - owner, VO, network server). - \TODO{JDL flags?} - - \item \emph {Refresh of a notification} When a new notification is + \marginpar{\LB 2.0 only}% + In version 1.x there is a restriction that at least one particular + JobId must be defined. In \LB 2.0 you can make a registration based + on other attributes without referencing a particular JobId (you can + select owner, VO, network server). It is also a feature of \LB 2.0 + only, that you can use attributes derived from JDL (VO). + + \item \emph {Refresh of a notification}. When a new notification is created using \verb'edg_wll_NotifNew' call, the notification validity parameter is intended to set the refresh period, not the lifetime of the notification itself. The owner of notification must periodically call \verb'edg_wll_NotifRefresh' to ensure validity of - the notification. + the notification. See also next sections. \item It is possible to \emph{change existing notification} (its conditions) by \verb'edg_wll_NotifChange' call. - \item If user does not want to receive notifications any more, + \item If the user does not want to receive notifications anymore, \verb'edg_wll_NotifDrop' call \emph{removes the registration} for notifications from \LB server. \end{itemize} @@ -88,10 +88,11 @@ funcions. \subsection{Receive data} To receive data from a notificaton the API provides \verb'edg_wll_NotifReceive' call. It returns first incoming -notification if at least one is available or waits a specified timeout. You can -also set the timeout to zero if you want to poll. +notification if at least one is available or waits for a new one. The +maximal waiting time is limited to a specified timeout. You can also set the +timeout to zero if you want to poll. -If the user wants to start receiving the notifications from different +If the user wants to move the client receiving the notifications to a different machine than where the registration was done, it is possible. The client must use the \verb'edg_wll_NotifBind' call to inform the notification infrastructure (interlogger) about its location change. @@ -133,6 +134,49 @@ the whole set of registrations. Will receive a first notification from any of registations. \subsubsection{Operator CHANGED} +\marginpar{\LB 2.0 only}% +The notification events are generated by LB server based on primary +events send by grid components. Each of the primary events (called LB +events) generates one notification event to be possibly sent to the +client but not each LB event for example changes the job state. You +can use notification conditions to filter only the notification +events you want to receive, for example $job status = done$. If you +want to receive all job status changes you need to setup a condition +on job status attribute using special unary operator +\verb'CHANGED'. Otherwise (without any condition) you will receive +more events that you want -- even events where job state was not +changed. Operator \verb'CHANGED' is available only in \LB 2.0. + +\subsubsection{Returned attributes} +\marginpar{\LB 2.0 only}% +Each LB notification contains a structure describing job state +including job's JDL. For optimization purposes the API user can set +the JDL flag in \verb'edg_wll_NotifNew' flags parameter to prevent +sending of unnecessary JDL data with each notification. + +\subsubsection{Timeouts} +A user of the notification API should distinguish between various timeouts: +\begin{itemize} +\item \emph{Registration validity timeout.} Each registration is +soft-state entity which must be refreshed in a given timeout. If there +is no refresh received by the LB server in validity timeout period the +registration is dropped. On the other hand for that timeout all events +are queued in the LB infrastructure for the case of client's temporary +unavailability. + +The registration validity timeout can be set by the user when creating +a new registration but only to a reasonably short time period. The +validity of a registration is driven by the refresh process not the +timeout itself. For a exaple of registration management via the +refresh calls please see the \verb'glite-lb-notify' source code as +mentioned above. + +\item \emph{Receive call timeout.} The timeout used in the +\verb'edg_wll_NotifReceive' call is inteded just to control the +receiving loop. It is the maximum time the API can spend in the call +before returning the control to user code. + +\end{itemize} \subsection{Registering and receiving notification example} -- 1.8.2.3