\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'<errno.h>' error codes.
+\item[\LB specific] a~few errors can't be intuitively mapped to
+\verb'<errno.h>', 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}).
git://scientific.zcu.cz / jra1mw.git / commitdiff