From 464321ee8f6afb0e1d63cd2309c29b10cbfdc275 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ji=C5=99=C3=AD=20Sitera?= Date: Tue, 16 Dec 2008 16:12:30 +0000 Subject: [PATCH] First version of notification chapter rewrite. Must be cleaned up and the example is still waiting to its new version. --- org.glite.lb.doc/src/notification_api.tex | 118 +++++++++++++++++++++--------- 1 file changed, 82 insertions(+), 36 deletions(-) diff --git a/org.glite.lb.doc/src/notification_api.tex b/org.glite.lb.doc/src/notification_api.tex index a6e5939..7447fc2 100644 --- a/org.glite.lb.doc/src/notification_api.tex +++ b/org.glite.lb.doc/src/notification_api.tex @@ -5,10 +5,88 @@ \TODO{sitera: prepsat ve stejnem duchu jako predchozi kapitoly, zminit novinky v \LBnew} -The purpose of this section is demonstrating the usage of the \LB\ notification API. Two examples of basic API usage are given. - - -\subsection{Registering and receiving notification} +The \LB\ notification API is another kind of \LB\ consumer API and +provides streaming publish/subscribe model instead of query/response +model. It is designed to provide the same information and use the same +query conditions encoding as the consumer API described in sec.~\ref{s:Consumer-API}. + +Basic usage of the \LB\ notification API is described in the \LB +user's guide (\cite{lbug}) in section ``Tools'' as there is described +a tool called \verb'glite-lb-notify' which is a thin wrapper around +the \LB\ notification API. Its source code can also serve as a +complete exaple of the \LB\ notification API usage. + +The \LB\ notification API have currently only C language binding. + +\subsection{Header files} +\begin{table}[h] +\begin{tabularx}{\textwidth}{>{\tt}lX} +glite/lb/notification.h & Prototypes for all notification API functions. \\ +\end{tabularx} +\end{table} + +\subsection{Call semantics} +The API have two main parts: notification subscription management and +receiving data. Each subscription (registration of notification) have +its unique identifier called \emph{Notification ID} represented by +type \verb'edg_wll_NotifId'. This ID is returned to the caller when +creating a new notification and it is used by receiver to get data +from the notification. + +The API uses \verb'EDG_WLL_NOTIF_SERVER' context parameter to set the +source server (\LB server name and port). + +The typical notification workflow consist of 3 tasks: +\begin{itemize} + \item Create a new notification registration based on given conditions. + \item Refresh the registration. Each notification registration is + soft-state registration and must be regullarly refreshed by the + owner. + \item Receiving the data from notification. The \LB infrastructure + provides data queuing and garantied delivery (while the registration + is valid). +\end{itemize} + +For complete reference of all API funcions please see the header +file. The next sessions briefly describe main facts about API +funcions. + +\subsection{Notification subscription and management} +To create a new notification registration 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). + +A new notification is created using \lstinline'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 \lstinline'edg_wll_NotifRefresh' to ensure validity +of the notification. + +If user does not want to receive notifications any more, +\lstinline'edg_wll_NotifDrop' call removes the registration for +notifications from \LB server. + +It is possible to change existing notification (conditions) by +\lstinline'edg_wll_NotifChange' call. + +\subsection{Receive data} +To receive data from a notificaton the API provides +\lstinline'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. + +If the user wants to start receiving the notifications from different machine +than where the registration was done, it is possible but the +\verb'edg_wll_NotifBind' call must be used. + +\TODO{Reusing of socket} + +\TODO{Normal usage of \lstinline'edg_wll_NotifCloseFd'? Shoul be used?} + +\subsection{Registering and receiving notification example} The following example registers on \LB\ server to receive notifications triggered by events belonging to job with \verb'jobid' and waits for notification until \verb'timeout'. The code assumes the user to prepare a~reasonable value in \verb'jobid' @@ -98,36 +176,4 @@ Notifications are recieved with the \verb'edg_wll_NotifReceive' call. If no notification is ready for delivery, the call waits until some notification arrival or timeout. -If user does not want to receive notifications any more, \verb'edg_wll_NotifDrop' call removes the registration for notifications from \LB server. - - -\subsection{Changing destination for notifications} - -The second example illustrates how to receive notifications from different host or different application. - -Let us suppose that user is registered for receiving notifications on \LB\ server. She obtained a notification ID and information how long this registration will be valid as described in the previous example but she did not delete registration with \verb'edg_wll_NotifDrop'. - -If the registration is still valid, she can start new client for receiving notifications, even from different machine, using notification ID returned during registration in previous step. - -The sequence of function calls (without catching errors) would be as follows: - -\begin{verbatim} - edg_wll_NotifId nid; - char *ns; // notification ID string returned - // in previous example - ... - edg_wll_NotifIdParse(ns, &nid); - edg_wll_NotifBind(ctx, nid, -1, NULL, &valid); - - /* prolong the registration validity if necessary */ - if (...validity close to expire...) - edg_wll_NotifRefresh(ctx, nid, &valid); - - edg_wll_NotifReceive(ctx, -1, &timeout, &status, &recv_notif_id); - ... -\end{verbatim} -The call \verb'edg_wll_NotifReceive' will return any notification -that was generated while there was no listening client for it. -If there are none, it will wait for new notifications as in the previous -example. -- 1.8.2.3