From 1d2f712ec37fbdda60dbf62ac049c5d9ac7624d6 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Fri, 14 Mar 2008 19:51:22 +0000 Subject: [PATCH] some text --- org.glite.lb.doc/src/LBDG-Common.tex | 2 + org.glite.lb.doc/src/LBDG-Introduction.tex | 77 ++++++++++++++++++++++++++++++ org.glite.lb.doc/src/LBDG.tex | 31 ++++++++++++ 3 files changed, 110 insertions(+) diff --git a/org.glite.lb.doc/src/LBDG-Common.tex b/org.glite.lb.doc/src/LBDG-Common.tex index dff668c..557103a 100644 --- a/org.glite.lb.doc/src/LBDG-Common.tex +++ b/org.glite.lb.doc/src/LBDG-Common.tex @@ -1,2 +1,4 @@ \section{\LB\ Common} \TODO{Add the information about LB common - list of header files, important functions and data types and their description, etc.} + + diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 1ac1ed9..8b88ce3 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -1,2 +1,79 @@ \section{Introduction} \TODO{Add the information from the "Best practices" workshop, i.e. information how the whole LB is coded, why C, what were the general techniques - context, connection pool, .T templates description, etc.} + +\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. + +Few API function return \verb'char *'. In such a~case \verb'NULL' indicates +an error, non-null value means success. + +\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. + +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. + +\item[INOUT] an argument taken as an input and modified by the function. +Typically it is the \LB context. + +\end{description} + +\subsubsection{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 and Parameter Settings} +\label{s:context} + +All the API functions refer to a~\emph{context} argument. +The context type \verb'edg_wll_Context' is opaque. +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 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, see Sect.~\ref{s:sequence}), +and keeps track of an event \emph{sequence code} for the job +(detailed description in~\cite{lbarch}). diff --git a/org.glite.lb.doc/src/LBDG.tex b/org.glite.lb.doc/src/LBDG.tex index 6f0973d..90c8a0f 100644 --- a/org.glite.lb.doc/src/LBDG.tex +++ b/org.glite.lb.doc/src/LBDG.tex @@ -18,6 +18,37 @@ Interface is described in details together with programing examples. } \begin{document} + +% ----- BEGIN COPY ----- +% copied from org.glite.lb.client/doc/api/api.tex in hope it could be useful + +%\parindent=0pt +%\parskip=\smallskipamount + +\makeatletter +\def\jobid{\textit{JobId}\xspace} +\def\@tti[#1]{\item[{\normalfont\texttt{#1}}]\catcode`\_=8} +\def\tti{\catcode`\_=11\noexpand\@tti} +\newlength{\tw} + +\def\synopsis{\catcode`\_=11\noexpand\@synopsis} +\def\@synopsis#1#2{ +\tw=\linewidth +\advance\tw-2em +\texttt{#1(}\\ +\strut\hskip2em\begin{tabularx}\tw{>{\begingroup\tt}l<{\endgroup}lX} +#2 +\end{tabularx}\\ +\texttt) +\catcode`\_=8 +} + +\def\Synopsis{\subsubsection*{Synopsis}} +\def\Description{\subsubsection*{Description}} +\def\Return{\subsubsection*{Return values}} + +% ----- END COPY ----- + \input{frontmatter} \tableofcontents -- 1.8.2.3