From bc71853ca8a7576bc3f8516904c9eef6c6e346a2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Tue, 30 Mar 2010 20:11:32 +0000 Subject: [PATCH] some c++ api docs --- org.glite.lb.doc/src/LBDG-Introduction.tex | 16 ++++++++++------ org.glite.lb.doc/src/consumer_api.tex | 22 +++++++++++++++++++--- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 1ce619d..2d17120 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -93,7 +93,7 @@ and external dependencies: For platforms supported by gLite officially all the required packages can be downloaded from \url{http://www.glite.org}. -However, \LB\ is fairly portable and it can be build on other +However, \LB\ is fairly portable and it can be built on other platforms fairly smoothly. Detailed instructions on getting the sources, including the required @@ -513,7 +513,7 @@ source file, line and method the exception was thrown from (possibly accumulating information from other exception). \marginpar{Reference counting}% -When the C++ \LB library calls return allocated structures, they are +When the C \LB library calls return allocated structures, they are encapsulated within C++ accessor objects. Copying the C++ object does not copy the underlying structure, it increases the reference count instead, making use of the same allocated data. The reference count is @@ -545,7 +545,7 @@ glite/lb/LoggingExceptions.h & Exception class for \LB--specific errors.\\ \subsubsection{Building Programs} The recommended way to build programs using the C++ \LB library is, -like in the C case, use the \verb'libtool' utility: +like in the C case, to use the \verb'libtool' utility: \begin{verbatim} flavour=gcc32dbg libtool --mode=compile gcc -c example1.c util.c \ @@ -588,8 +588,8 @@ JobId jobid(Hostname("some.host")); In that case new unique part is generated automatically. \end{itemize} Apart from that there are the usual copy constructor and assignment -operator that do the deep copy, and the destructor that deallocates -the memory. +operator that make deep copy of the object, and the destructor that +deallocates the memory. \marginpar{Data access}% The \verb'JobId' class provides methods for obtaining the host, port @@ -603,6 +603,8 @@ representations. The following example illustrates these features: JobId a(Hostname("me")); JobId b(Hostname("me")); +cout << "jobid host and port: " << a.host() << ", " << +a.port() << endl; cout << (a < b) ? a.unique() : b.unique() << " comes first" << endl; cout << "Complete jobid: " << a.toString() << endl; \end{lstlisting} @@ -610,9 +612,11 @@ cout << "Complete jobid: " << a.toString() << endl; \subsubsection{Exception} The \verb'glite::lb::Exception' is a base class for all exceptions thrown by the \LB library. It inherits from \verb'std::runtime_error' -and adds no additional members or methods except constructors: +and adds no additional members or methods except constructors. The +typical usage is this: \begin{lstlisting} try { + // some code with LB calls } catch (glite::lb::Exception &e) { cerr << "LB library exception: " << e.what() << endl; } diff --git a/org.glite.lb.doc/src/consumer_api.tex b/org.glite.lb.doc/src/consumer_api.tex index 9b4accd..314c493 100644 --- a/org.glite.lb.doc/src/consumer_api.tex +++ b/org.glite.lb.doc/src/consumer_api.tex @@ -270,7 +270,7 @@ The query condition is the following: \lstinputlisting[title={\bf File: }\lstname,numbers=left,linerange=queryrec-end\ queryrec]{cons_example2.c} -As clearly seen, there are three lists supplied to +As can be clearly seen, there are three lists supplied to \texttt{edg\_wll\_QueryJobsExt()}. The first list specifies the owner of the job, the second list provides the required status (\texttt{Running}) and the last list specifies the two destinations. @@ -324,7 +324,6 @@ demonstrated in the client example \texttt{job\_log.c} (in the client module). \subsection{C++ Language Binding} -\TODO{michal} The querying C++ \LB API is modelled after the C \LB API using these basic principles: \begin{itemize} \item queries are expressed as vectors of @@ -355,10 +354,27 @@ specific queries. \\ \end{table} \subsubsection{QueryRecord} +The \verb'glite::lb::QueryRecord' class serves as the base for mapping +the \LB query language into C++, similarly to the C counterpart +\verb'edg_wll_QueryRecord'. The \verb'QueryRecord' object represents +condition on value of single attribute: +\begin{lstlisting} + using namespace glite::lb; + + QueryRecord a(QueryRecord::OWNER, QueryRecord::EQUAL, "me"); +\end{lstlisting} +The \verb'QueryRecord' class defines symbolic names for attributes (in +fact just aliases to \verb'EDG_WLL_QUERY_ATTR_' symbols described in table\ +\ref{t:cqueryattr}) and for conditionals (aliases to +\verb'EDG_WLL_QUERY_OP_' symbols, table\ \ref{t:cqueryop}). The last +parameter to the \verb'QueryRecord' constructor is the attribute +value. + + \subsubsection{Event} The objects of class \verb'glite::lb::Event' are returned by the \LB event -queries. The \verb'Event' class introduces symbolic names for event +queries. The \verb'Event' class intgstr roduces symbolic names for event type (enum \verb'Event::Type'), event attributes (enum \verb'Event::Attr') and their types (enum \verb'Event::AttrType'), feature not available through the C API, as -- 1.8.2.3