From 1732af9c4419cd17d8aee5928a98de3211f5244f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Fri, 18 Jul 2008 17:14:22 +0000 Subject: [PATCH] mainly introduction and common description --- org.glite.lb.doc/src/LBDG-Introduction.tex | 312 ++++++++++++++++------------- org.glite.lb.doc/src/LBDG.tex | 7 + org.glite.lb.doc/src/producer_api.tex | 17 +- org.glite.lb.doc/src/web_services.tex | 1 + 4 files changed, 196 insertions(+), 141 deletions(-) diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 01bb3f8..aab8e2f 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -1,155 +1,212 @@ % -*- mode: latex -*- -\section{\LB API design notes} +\section{Introduction} -\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}). +This document is intented to guide the reader through basic steps +of writing, compiling and running programs communicating with the \LB +service using the \LB library. It is not intended as a complete API +reference; for this, the reader is referred to the C or C++ header +files, which are thoroughly documented using the doxygen--style +comments. 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). +\item \textit{\LB Producer API} (section \ref{s:ProdOverview}) is used +to create and send events to the \LB server (proxy), +\item \textit{\LB Consumer API} (section \ref{s:ConsOverview}) and \textit{\LB +Notification API} (section \ref{s:NotifOverview}) 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}. +\texttt{org.glite.lb.common} and are described in section~\ref{s:common} + +\marginpar{Recommended reading} +Before you start reading this guide, it is recommended to accomodate +yourself with the \LB architecture described in the first part of the +\LB user's guide (\cite{LBUG}). +\input versions + +\subsection{General Guidelines} + +\marginpar{Naming conventions} +All names exported by the \LB library (function names, symbolic +constants) are prefixed to avoid name clashes. The prefix is +\lstinline'edg_wll_' for function names and \lstinline'EDG_WLL_' for +symbolic constants. + +\marginpar{Input and output arguments} +All input arguments in \LB API are designated \lstinline'const' (for simple +types) or have \texttt{const} in type name (for structures). + +If pointers are passed in output of function call (either as a return +value, output argument or part of structure), the corresponding +objects are \emph{always} allocated dynamically and have to be freed +when not used anymore. + +\marginpar{Opaque and transparent types} +Types used in \LB API are either opaque or transparent. \textit{Opaque +types} are considered internal to the library, their structure is not +exposed to users and is subject to change without notice. The only way +to modify opaque objects is to use API calls. Example of opaque type +is \lstinline'edg_wll_Context'. + +Structure of \textit{transparent types} is completely visible to +user, is well documented and no incompatible changes will be done +without notice. Example of transparent type is +\lstinline'edg_wll_Event'. + +\marginpar{Return values} +The return type of most of the API functions is \lstinline'int'. +Unless specified otherwise, zero return value means success, non-zero +failure. Standard error codes from \lstinline'' are used as +much as possible. In a few cases the error can not be intuitively +mapped and \LB specific error value greater than +\lstinline'EDG_WLL_ERROR_BASE' is returned. + +Few API function return \lstinline'char *'. In such a~case +\lstinline'NULL' indicates an error, non-null value means success. \subsection{Context and Parameter Settings} \label{s: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. - -Context is used to set and keep various parameters of the library -(\eg\ default server addresses, timeouts, \dots). -Upon initialization, all the parameters are assigned default values. -However, many of the parameters take their default value from environment -variables. If the corresponding environment variable is set, -the parameter is initialized to its value instead of the default. -Note that a~few parameters cannot be assigned default value; consequently -setting them either in environment or with an explicit API call -is mandatory before using the appropriate part of the API. +The \LB library does not maintain internal state, all the API +functions refer to a~\emph{context} argument instead. +Context object preserves state information among the various API +calls, the state including \LB library parameters (\eg security +context, server addresses, timeouts), reference to open connections +(connection pool), error state etc. + +The API caller can create many context objects which are guaranteed +to be independent on one another. In this way thread--safety of the +library is achieved as long as the context is not used by more threads +at the same time. One thread may use more than one context, though. + +Upon context initialization, all the parameters are assigned default +values. If not set explicitely, many of the parameters take their +value from environment variables. If the corresponding environment +variable is set, the parameter is initialized to its value instead of +the default. Note that a~few parameters cannot be assigned default +value; consequently setting them either in environment or with an +explicit API call is mandatory before using the appropriate part of +the API. The context also stores details on errors of the recent API call. -For use with the \emph{producer} calls (see Sect.~\ref{s:producer}) -the context has to be assigned a~single \jobid -(with the \verb'edg_wll_SetLoggingJob' call), -and keeps track of an event \emph{sequence code} for the job -(see~\cite{LBUG}, detailed description in~\cite{lbarch}). +For use with the \emph{producer} calls (see section~\ref{s:producer}) +the context has to be assigned a~single \jobid (with the +\lstinline'edg_wll_SetLoggingJob' call), and keeps track of an event +\emph{sequence code} for the job (see~\cite{LBUG}, detailed +description in~\cite{lbarch}). +The context object and its API functions are described more thoroughly +in section~\ref{s:edg_wll_context}. \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. +The \LB library maintains pool of client--server connections to +improve performance (creating SSL connection is heavy--weight +operation). The connections are transparently shared and reused by all +contexts/threads to eliminate the overhead of secure channel +establishment. This behaviour is completely hidden by the library. -\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. -If it is a~pointer, the C prototype includes \verb'const' (which is omitted in -this document for the sake of readability). -\item[OUT] pure output argument. The function expects a~pointer and fills in -the pointed object. +\section{\LB Common Components} +\label{s:common} -If the argument is \verb'**', or a~structure containing pointers, -the returned objects are \emph{always} dynamically allocated, -and has to be freed when not used anymore. -The same holds for directly returned pointers. +\subsection{Header Files} -\item[INOUT] an argument taken as an input and modified by the function. -Typically it is the \LB context. +Header files for the structures and functions 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. -\end{description} +\begin{table}[h] +\label{t:cheaders} +\begin{tabularx}{\textwidth}{>{\tt}lX} +glite/jobid/cjobid.h & Definition of job identifier. \\ +glite/lb/context.h & Definition of context structure and parameters. \\ +glite/lb/events.h & \LB event data structure.\\ +glite/lb/jobstat.h & Job status structure returned by consumer API.\\ +\end{tabularx} +\caption{Header files for common structures} +\end{table} -\subsection{Datatypes} -The API uses two classes of custom datatypes: -\begin{description} -\item[opaque types] (\eg context, jobid) do not expose their structure -to the user. -The only way to access them is via the API functions. -The internal structure of those may be subject to change. - -\item[transparent types] (\eg event, status) expose the structure to the -user. The structure is documented and no incompatible changes will be done -without notice. -\end{description} +\subsection{Context} +\label{s:edg_wll_context} +\marginpar{Context initialization} +Opaque data structure representing \LB API context (see +section~\ref{s:context}) is named \lstinline'edg_wll_Context'. +The context must be initialized before the first \LB API call: +\begin{lstlisting} +#include + +edg_wll_Context ctx; +edg_wll_InitContext(&ctx); +\end{lstlisting} + +\marginpar{Parameter setting} +The context parameters can be set explicitly by calling +\lstinline'edg_wll_SetParam(edg_wll_Context *, edg_wll_ContextParam, ...)' +function. The second argument is symbolic name of the context +parameter; parameters specific for producer and consumer API are +described in respective API sections, the common parameters are: -\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} -\item[0] success -\item[errno] an error occured, the nature of the error -matches meaning of one of standard \verb'' error codes. -\item[\LB specific] a~few errors can't be intuitively mapped to -\verb'', therefore the are specific \LB error codes, starting from \verb'EDG_WLL_ERROR_BASE'. -\end{description} -See Sect.~\ref{s:error} for details on error handling. +\begin{table}[h] +\begin{tabularx}{\textwidth}{llX} +{\bf C name} & {\bf Env. variable} & {\bf Description} \\ +\hline +\lstinline'EDG_WLL_PARAM_X509_KEY' & \lstinline'X509_USER_KEY' & Key file to use for +authentication. \\ +\lstinline'EDG_WLL_PARAM_X509_CERT' & \lstinline'X509_USER_CERT' & Certificate file to use +for authentication. \\ +\lstinline'EDG_WLL_PARAM_CONNPOOL_SIZE' & & Maximum number +of open connections maintained by the library. \\ +\end{tabularx} +\end{table} -Few API function return \verb'char *'. In such a~case \verb'NULL' indicates -an error, non-null value means success. +The third argument is parameter value, which can be of type +\lstinline'int', \lstinline'char *' or \lstinline'struct timeval *'. +If the parameter value is set to \lstinline'NULL' (or 0), the +parameter is reset to the default value. -\section{\LB common general components} -\label{s:common} +If you want to obtain current value of some context parameter, call +\lstinline'edg_wll_GetParam(edg_wll_Context, edg_wll_ContextParam, ...)' function: +\begin{lstlisting} +char *cert_file; -\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} +edg_wll_GetParam(ctx, EDG_WLL_PARAM_X509_CERT, &cert_file); +printf("Certificate used: %s\n", cert_file); +free(cert_file); +\end{lstlisting} +The third argument points at variable with type corresponding to the +requested parameter. Do not forget to free the result. \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?} - -\subsection{JobId} +\marginpar{Obtaining error details} +When \LB API call returns error, additional details can be obtained +from the context: +\begin{lstlisting} +char *err_text,*err_desc; + +edg_wll_Error(ctx, &err_text, &err_desc); +fprintf(stderr, "LB library error: %s (%s)\n", err_text, err_desc); +free(err_text); +free(err_desc); +\end{lstlisting} + +\marginpar{Context deallocation} +If the context is needed no more, deallocate it: +\begin{lstlisting} +edg_wll_FreeContext(ctx); +\end{lstlisting} + +For more information see file \texttt{glite/lb/context.h} + +\subsection{Job Identification} 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 @@ -184,7 +241,7 @@ changed between \LB versions: \end{itemize} \end{description} -\subsection{edg\_wll\_Event} +\subsection{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 @@ -206,7 +263,7 @@ structure. For more information see file \texttt{org.glite.lb.types/types.T} \TODO{example - Michal?} -\subsection{edg\_wll\_JobStat} +\subsection{Job Status} 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 @@ -221,20 +278,3 @@ attributes: -\subsection{\LB common header files} - -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.\\ -glite/lb/jobstat.h & Job status structure returned by consumer API.\\ -\end{tabularx} -\end{table} - - diff --git a/org.glite.lb.doc/src/LBDG.tex b/org.glite.lb.doc/src/LBDG.tex index 958bfbb..0254f92 100644 --- a/org.glite.lb.doc/src/LBDG.tex +++ b/org.glite.lb.doc/src/LBDG.tex @@ -2,6 +2,7 @@ \documentclass{egee} \input{definitions} +\def\LB{LB\xspace} \title{Logging and Bookkeeping} \Subtitle{Developer's Guide} @@ -19,7 +20,13 @@ Interface is described in details together with programing examples. } \usepackage{listings} +%\setlength{\marginparwidth}{1.2in} +\let\oldmarginpar\marginpar +\renewcommand\marginpar[1]{\-\oldmarginpar[\raggedleft\footnotesize #1]% +{\raggedright\footnotesize #1}} + \begin{document} +\reversemarginpar \lstset{language=C,basicstyle=\footnotesize,numbers=left,breaklines=true} % ----- BEGIN COPY ----- diff --git a/org.glite.lb.doc/src/producer_api.tex b/org.glite.lb.doc/src/producer_api.tex index 69e2bbd..2f229ab 100644 --- a/org.glite.lb.doc/src/producer_api.tex +++ b/org.glite.lb.doc/src/producer_api.tex @@ -6,9 +6,10 @@ The \LB\ logging API (or producer API) is used to create and deliver events to the \LB\ server and/or proxy, depending on the function used: +\TODO{verify ChangeACL} \begin{table}[h] \begin{tabularx}{\textwidth}{lX} -\bf Function & \bf Delivered to \\ +\bf Function & \bf Delivers to \\ \hline \small\verb'edg_wll_LogEvent(...)' & asynchronously through locallogger/interlogger to the \LB\ server \\ @@ -16,7 +17,7 @@ locallogger/interlogger to the \LB\ server \\ locallogger/interlogger to the \LB\ server \\ \small\verb'edg_wll_LogEventProxy(...)' & through \LB\ proxy to the \LB\ server \\ \small\verb'edg_wll_Register*(...)' & directly to both \LB\ server and proxy \\ -\small\verb'edg_wll_ChangeACL(...)' & directly to the \LB\ server \\ +\small\verb'edg_wll_ChangeACL(...)' & synchronously to the \LB\ server \\ \end{tabularx} \end{table} @@ -52,12 +53,13 @@ Job registrations are all synchronous. \begin{table}[h] \begin{tabularx}{\textwidth}{>{\tt}lX} +%glite/lb/context.h & Definition of context structure and parameters. \\ glite/lb/producer.h & Prototypes for all event logging functions. \\ \end{tabularx} \end{table} \subsection{Context parameters} -The following table summarizes context parameters relevant to the +The table\ref{} summarizes context parameters relevant to the event logging. If parameter is not set in the context explicitly, the \LB\ library will search for value of corresponding environment variable. The symbolic C names should be prepended with @@ -87,17 +89,19 @@ The \verb'GLITE_WMS_LOG_DESTINATION' environment variable contains both locallogger host and port separated by colon (\ie\ ``host:port''). \subsection{Return values} -The logging functions return 0 on success and one of {\texttt EINVAL, -ENOSPC, ENOMEM, ECONNREFUSED, EAGAIN} on error. If {\texttt EAGAIN} is +The logging functions return 0 on success and one of \texttt{EINVAL, +ENOSPC, ENOMEM, ECONNREFUSED, EAGAIN} on error. If \texttt{EAGAIN} is returned, the function should be called again to retry the delivery; it is not guaranteed, however, that the event was not delivered by the first call. Possibly duplicated events are discarded by the \LB\ server or proxy. +\TODO{check these} The synchronous variants of logging functions can in addition return \verb'EDG_WLL_ERROR_NOJOBID' or \verb'EDG_WLL_ERROR_DB_DUP_KEY'. \subsection{Logging events} +\TODO{odkaz na soubor} In this section we will give an example how to log an UserTag event to the \LB. @@ -132,3 +136,6 @@ err = edg_wll_LogUserTag(ctx, name, value); \end{lstlisting} \subsection{Java binding} +\TODO{mirek} + +\TODO{C, C++, WS doplnit jako subsekce} \ No newline at end of file diff --git a/org.glite.lb.doc/src/web_services.tex b/org.glite.lb.doc/src/web_services.tex index 4717157..8cb9a15 100644 --- a/org.glite.lb.doc/src/web_services.tex +++ b/org.glite.lb.doc/src/web_services.tex @@ -1,6 +1,7 @@ % -*- mode: latex -*- \section{Using \LB\ Web Service} +\TODO{ljocha} \TODO{Presunout do consumera} -- 1.8.2.3