From 52c4e0b35d6ccb43954f80a9194e881dff7f7c6f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Thu, 17 Jul 2008 15:06:38 +0000 Subject: [PATCH] reshuffle --- org.glite.lb.doc/src/LBDG-Introduction.tex | 152 ++++++++++++++--------------- org.glite.lb.doc/src/producer_api.tex | 19 +++- 2 files changed, 93 insertions(+), 78 deletions(-) diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 2c51209..01bb3f8 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -1,31 +1,39 @@ % -*- mode: latex -*- -\section{\LB API introduction} +\section{\LB API design notes} + \input versions A recomended prerequisity for reader of this developer's guide is the \LB architecture description located in the first part of the \LB user's guide (\cite{LBUG}). -The whole \LB service shares a number of common concepts and -principles used to design, develop and use the services. Most of -common data types and functions is separated in its own SW module called -\LB common (\texttt{org.glite.lb.common}). +The \LB API can be divided by functionality into two independent +parts: +\begin{itemize} +\item \textit{\LB Producer API} is used to create and send events to the \LB +server (proxy), +\item \textit{\LB Consumer API} and \textit{\LB +Notification API} are used to obtain information from the \LB server (proxy). +\end{itemize} +These two parts (and in fact the whole \LB service implementation) +share a number of common concepts, design principles, data types and +functions which we will describe first. Most of common data types and +functions are separated in its own SW module called +\texttt{org.glite.lb.common} described in section~\ref{s:common}. -\subsection{\LB API design notes} -\subsubsection{Context and Parameter Settings} +\subsection{Context and Parameter Settings} \label{s:context} -All the API functions refer to a~\emph{context} argument. See next -session for futher description of context type \verb'edg_wll_Context'. - +All the API functions refer to a~\emph{context} argument, which is +described more thoroughly in section~\ref{s:edg_wll_context}. Context objects preserve various status information (\eg\ connection to server) among the API calls. The API caller can create many context objects, those are guaranteed -to be independent on one another. -In this way thread-safety of the library is achieved -- -one context object has to be used by only one thread at time. +to be independent on one another. In this way thread-safety of the +library is achieved -- one context object has to be used by only one +thread at time. Context is used to set and keep various parameters of the library (\eg\ default server addresses, timeouts, \dots). @@ -45,27 +53,14 @@ the context has to be assigned a~single \jobid and keeps track of an event \emph{sequence code} for the job (see~\cite{LBUG}, detailed description in~\cite{lbarch}). -\subsubsection{Asynchronnous calls} -\LB library calls are typically asynchronnous. The typical call -- -loging a event -- is returned immediatelly and the success of the call -means that the first \LB infrastructure component takes over the event -for delivery. The event itself is queued for delivery to the \LB -server, so there is no guarantee that subsequent query will see the -event. This is not true for new job registration. It is the operation done -synchronously. - -The \LB proxy provides a \emph{local view} semantics. The \LB proxy -query semantics is synchronnous (there is a guarantee that a query -next to the event logging call will see the event) but only for events -logged through the particular \LB proxy instance. - -\subsubsection{Connection pool} + +\subsection{Connection pool} For better performance the \LB client library have a feature called connection pool -- a client--server connection is transparently reused by different threads/context to eliminate the overhead of secure channel establishment. -\subsubsection{Function arguments} +\subsection{Function arguments} In the following description the function arguments are classified as follows: \begin{description} \item[IN] pure input argument, not modified by the function. @@ -84,7 +79,7 @@ Typically it is the \LB context. \end{description} -\subsubsection{Datatypes} +\subsection{Datatypes} The API uses two classes of custom datatypes: \begin{description} \item[opaque types] (\eg context, jobid) do not expose their structure @@ -97,7 +92,7 @@ user. The structure is documented and no incompatible changes will be done without notice. \end{description} -\subsubsection{Return values} +\subsection{Return values} The return type of most of the API functions is return \verb'int'. Unless specified otherwise the returned values are as follows: \begin{description} @@ -112,9 +107,49 @@ See Sect.~\ref{s:error} for details on error handling. Few API function return \verb'char *'. In such a~case \verb'NULL' indicates an error, non-null value means success. -\subsection{\LB common general components} +\section{\LB common general components} +\label{s:common} + +\subsection{edg\_wll\_Context} +\label{s:edg_wll_context} +Data structure representing \LB API context (see +section~\ref{s:context}). There are parameters described in consumer +and producer API chapters which are stored in context and accessed by +funcions described below (\texttt{edg\_wll\_SetParam}) using +appropriate constants. Examples of common context parameters: +\begin{itemize} + \item \texttt{EDG\_WLL\_PARAM\_X509\_KEY} key file to use for authentication. + \item \texttt{EDG\_WLL\_PARAM\_X509\_CERT} certificate file to use for + authentication +\end{itemize} + +\TODO{Máme odkaz kde jsou popsany defaulty a vazby na promenne environmentu?} + +The context type is opaque. Operations with the type instance: +\begin{itemize} + \item \texttt{edg\_wll\_InitContext(OUT edg\_wll\_Context *context)} + Allocate and initialize a new context object. + \item \texttt{edg\_wll\_FreeContext(IN edg\_wll\_Context context)} + Destroy and free context object, performs the necessary cleanup + (closing pending connections etc.). + \item \texttt{edg\_wll\_SetParam(INOUT edg\_wll\_Context context, IN + edg\_wll\_ContextParam param, IN val)} Sets a context parameter to + a given value (supports different types of \texttt{val}). If the + value is NULL (pointer type) or 0 (int), the parameter is reset to + its default value (or the value given by environment variable), in + exactly the same way as on context initialization. + \item \texttt{edg\_wll\_GetParam(INOUT edg\_wll\_Context context, IN + edg\_wll\_ContextParam param, OUT val)} Gets current parameter + value. Different types of \texttt{val} supported. Please note that + if the value of parameter is a~default, an actual value is always + returned, not NULL or 0. + \item edg\_wll\_Error +\end{itemize} +For more information see file \texttt{context.h} + +\TODO{Referenced or inline example?} -\subsubsection{JobId} +\subsection{JobId} The primary entity of \LB is a job, identified by JobId -- a unique identifier of the job (see also \cite{LBUG}). The type representing the JobId is opaque, it's contents is hidden to the API users and @@ -149,7 +184,7 @@ changed between \LB versions: \end{itemize} \end{description} -\subsubsection{edg\_wll\_Event} +\subsection{edg\_wll\_Event} Data structure \texttt{edg\_wll\_Event} represents a \LB event, atomic data unit received and processed by \LB. It is a set of key--value pairs with predefined structure -- allowed event types and names of @@ -171,7 +206,7 @@ structure. For more information see file \texttt{org.glite.lb.types/types.T} \TODO{example - Michal?} -\subsubsection{edg\_wll\_JobStat} +\subsection{edg\_wll\_JobStat} Data type \texttt{edg\_wll\_JobStat} represents status of a job as computed by \LB from received events. The data structure have a common part and a job state specific part. Most important common @@ -185,51 +220,16 @@ attributes: \end{itemize} -\subsubsection{edg\_wll\_Context} -Data structure representing \LB API context (see -section~\ref{s:context}). There are parameters described in consumer -and producer API chapters which are stored in context and accessed by -funcions described below (\texttt{edg\_wll\_SetParam}) using -appropriate constants. Examples of common context parameters: -\begin{itemize} - \item \texttt{EDG\_WLL\_PARAM\_X509\_KEY} key file to use for authentication. - \item \texttt{EDG\_WLL\_PARAM\_X509\_CERT} certificate file to use for - authentication -\end{itemize} - -\TODO{Máme odkaz kde jsou popsany defaulty a vazby na promenne environmentu?} - -The context type is opaque. Operations with the type instance: -\begin{itemize} - \item \texttt{edg\_wll\_InitContext(OUT edg\_wll\_Context *context)} - Allocate and initialize a new context object. - \item \texttt{edg\_wll\_FreeContext(IN edg\_wll\_Context context)} - Destroy and free context object, performs the necessary cleanup - (closing pending connections etc.). - \item \texttt{edg\_wll\_SetParam(INOUT edg\_wll\_Context context, IN - edg\_wll\_ContextParam param, IN val)} Sets a context parameter to - a given value (supports different types of \texttt{val}). If the - value is NULL (pointer type) or 0 (int), the parameter is reset to - its default value (or the value given by environment variable), in - exactly the same way as on context initialization. - \item \texttt{edg\_wll\_GetParam(INOUT edg\_wll\_Context context, IN - edg\_wll\_ContextParam param, OUT val)} Gets current parameter - value. Different types of \texttt{val} supported. Please note that - if the value of parameter is a~default, an actual value is always - returned, not NULL or 0. - \item edg\_wll\_Error -\end{itemize} -For more information see file \texttt{context.h} - -\TODO{Referenced or inline example?} -\subsubsection{\LB common header files} +\subsection{\LB common header files} -Header files for mentioned common structures are summarized in the -following table, other important header files are described in the -next chapters (producer and consumer API). +Header files for the above mentioned common structures are summarized in the +table~\ref{t:cheaders}. If you use the producer and/or consumer API +described further in this document, you do not have to include them explicitly. \begin{table}[h] +\label{t:cheaders} +\caption{Header files for common structures} \begin{tabularx}{\textwidth}{>{\tt}lX} glite/lb/context.h & Definition of context structure and parameters. \\ glite/lb/events.h & \LB event data structure.\\ diff --git a/org.glite.lb.doc/src/producer_api.tex b/org.glite.lb.doc/src/producer_api.tex index 895ee87..69e2bbd 100644 --- a/org.glite.lb.doc/src/producer_api.tex +++ b/org.glite.lb.doc/src/producer_api.tex @@ -32,12 +32,27 @@ For most developers (\ie\ those not developing the WMS itself) the \verb'edg_wll_LogUserTag*(...)' and \verb'edg_wll_ChangeACL(...)' are the only functions of interest. +\subsection{Call semantics} +\LB producer calls generally do not have transaction semantics, the +query following succesful logging call is not guaranteed to see +updated \LB server state. The typical call -- loging an event -- is +returned immediatelly and the success of the call means that the first +\LB infrastructure component takes over the event and queues it for +delivery. If you require transaction semantics, you have to use +synchronous \verb'edg_wll_LogEventSync(...)' call. + +The \LB proxy on the other hand provides a \emph{local view} +semantics, events logged into proxy using +\verb'edg_wll_LogEventProxy(...)' are guaranteed to by accessible by +subsequent queries \emph{on that proxy}. + +Job registrations are all synchronous. + \subsection{Header files} \begin{table}[h] \begin{tabularx}{\textwidth}{>{\tt}lX} -glite/lb/context.h & Definition of context structure and parameters. \\ -{\bf glite/lb/producer.h} & Prototypes for all event logging functions. \\ +glite/lb/producer.h & Prototypes for all event logging functions. \\ \end{tabularx} \end{table} -- 1.8.2.3