% -*- 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).
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.
\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
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}
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
\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
\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
\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.\\
git://scientific.zcu.cz / jra1mw.git / commitdiff