From 87b8d3eb2c51fbb1fe759bbbfbaa1d39c2d70b22 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jan=20Posp=C3=AD=C5=A1il?= Date: Tue, 13 Nov 2007 17:42:10 +0000 Subject: [PATCH] initial import --- org.glite.lb.doc/Makefile | 39 +++ org.glite.lb.doc/src/caveats.tex | 84 +++++ org.glite.lb.doc/src/change_acl.tex | 68 ++++ org.glite.lb.doc/src/doxygen.sty | 64 ++++ org.glite.lb.doc/src/doxyhack.tex | 31 ++ org.glite.lb.doc/src/egee.cls | 504 ++++++++++++++++++++++++++++++ org.glite.lb.doc/src/frontmatter.tex | 39 +++ org.glite.lb.doc/src/interaction.tex | 44 +++ org.glite.lb.doc/src/notification_api.tex | 126 ++++++++ 9 files changed, 999 insertions(+) create mode 100644 org.glite.lb.doc/Makefile create mode 100644 org.glite.lb.doc/src/caveats.tex create mode 100644 org.glite.lb.doc/src/change_acl.tex create mode 100644 org.glite.lb.doc/src/doxygen.sty create mode 100644 org.glite.lb.doc/src/doxyhack.tex create mode 100644 org.glite.lb.doc/src/egee.cls create mode 100644 org.glite.lb.doc/src/frontmatter.tex create mode 100644 org.glite.lb.doc/src/interaction.tex create mode 100644 org.glite.lb.doc/src/notification_api.tex diff --git a/org.glite.lb.doc/Makefile b/org.glite.lb.doc/Makefile new file mode 100644 index 0000000..2ba0f99 --- /dev/null +++ b/org.glite.lb.doc/Makefile @@ -0,0 +1,39 @@ +# Default values +top_srcdir=. +stagedir=. +globalprefix=glite +lbprefix=lb +package=glite-lb-doc +version=0.0.0 +PREFIX=/opt/glite + +-include Makefile.inc + +VPATH = ${top_srcdir}/src +KPATH = TEXINPUTS=".:$(VPATH)//:" +LATEX = $(KPATH) latex +PDFLATEX = $(KPATH) pdflatex +BIBTEX = $(KPATH) bibtex +DVIPS = $(KPATH) dvips + +default: LBUG.pdf + +%.dvi: %.tex + $(LATEX) $< +# $(BIBTEX) `basename $< .tex` +# $(LATEX) $< + $(LATEX) $< + +%.ps: %.dvi + $(DVIPS) -ta4 -o $@ $< + +%.pdf: %.tex + $(PDFLATEX) $< +# $(BIBTEX) `basename $< .tex` +# $(PDFLATEX) $< + $(PDFLATEX) $< + +clean: + rm -rvf LBUG* + +.PHONY: all clean purge ps pdf diff --git a/org.glite.lb.doc/src/caveats.tex b/org.glite.lb.doc/src/caveats.tex new file mode 100644 index 0000000..2c2c0e0 --- /dev/null +++ b/org.glite.lb.doc/src/caveats.tex @@ -0,0 +1,84 @@ +\subsection{Indexed attributes}\label{ConsIndx} +\LB\ queries can be fairly complicated and they can potentially return large +amounts of data. In such cases, there is a~risk of server overload. +In order to prevent the overload, every \LB\ server configuration +includes a~set of configurable \emph{indices}, empty by default +(job ID is always indexed). +In general, at least one indexed attribute must be +present in each query\,---\,queries over only attributes without indices +are refused. + +Unfortunately, in some cases queries that may be considered very important from +the user's point of view (like all user's jobs) fall into this category. +Indexing specific attributes makes these queries tractable +(while increasing the risk of server overload). +It's left up to the server administrator to decide which query types are +supported by configuring indices over attribute sets of desired queries using +the \texttt{glite-lb-bkindex} utility. +I.\,e.\ if the attribute \texttt{EDG\_WLL\_QUERY\_ATTR\_OWNER} is not indexed, +some of +queries in the presented examples +% odkazuje na totez :-( (\eg\ Sect.'s~\ref{JQ-auj},\ref{JQ-rj}) +(Sect.'s~\ref{JQ-auj}) +are forbidden. + +\subsection{Timeouts} + +All blocking \LB\ API calls are subject to timeouts. Timeout values can be changed +from their respective defaults with \texttt{edg\_wll\_SetParam} +call or using variables of the process environment (floating point number of seconds). + +\begin{tabular}{lcll} +affected calls&default(max)¶meter&env. variable\\ +async. logging&120 (1800)&\texttt{EDG\_WLL\_PARAM\_LOG\_TIMEOUT}&\texttt{EDG\_WL\_LOG\_TIMEOUT}\\ +sync. logging&120 (1800)&\texttt{EDG\_WLL\_PARAM\_LOG\_SYNC\_TIMEOUT}&\texttt{EDG\_WL\_LOG\_SYNC\_TIMEOUT}\\ +queries&120 (1800)&\texttt{EDG\_WLL\_PARAM\_QUERY\_TIMEOUT}&\texttt{EDG\_WL\_QUERY\_TIMEOUT}\\ +notifications&120 (1800)&\texttt{EDG\_WLL\_PARAM\_NOTIF\_TIMEOUT}&\texttt{EDG\_WL\_NOTIF\_TIMEOUT}\\ +\end{tabular} + +\subsection{Timestamps} +Timestamps of \LB\ event is recorded by the process calling a~logging API call. It is strongly recommended +to keep clocks of all systems that produce \LB\ events (UI, WM, WN) in reasonable synchronization so that +timestamp attributes of events and job status can be interpreted easily. + +On the other hand, timestamps are not authoritative when \LB\ events +are sorted in order to compute job state\Dash a~more robust mechanism +of the hierarchical \LB\ sequence code is used instead. +Consequently, strict timestamp sorting of events coming from desynchronised +sources may give different (incorrect) results from what \LB\ reports in job +state. + +\subsection{Size limitations} + +Current implementation of \LB\ has a~few built-in size limits, mostly related +to schema of underlaying MySQL database. By default, the limits are: + +\begin{tabular}{lc} +item & maximum size\\ +user certificate subject&255 bytes\\ +event attribute (JDL etc.) &16 megabytes\\ +tag name&200 bytes\\ +tag value&255 bytes\\ +job ACL&16 megabytes\\ +notification destination&200 bytes\\ +\end{tabular} + +The restriction on tag value is twofold. +Values up to 16\,MB may be logged and retrieved as raw events. +However, when reported in job state longer values are truncated to 255 bytes. +The restriction is inherited from MySQL limit on index size. + +\subsection{Running startup scripts} + +Startup scripts of the \LB\ service daemons should not be called without preconditions +being satisfied, \eg\ one should not try to start a~service when it is already running +or try to restart it from a~cron job without checking whether the machine is shutting down +at the time. + +\subsection{Dependencies} + +It is strongly discouraged to use \LB\ with different revisions +of external dependencies (MySQL, Globus Toolkit) +than those described in the release documentation. While the \LB\ has been designed to achieve +reasonable backward and forward compatibility, some disruptive changes in minor revisions +of external software have been observed before. diff --git a/org.glite.lb.doc/src/change_acl.tex b/org.glite.lb.doc/src/change_acl.tex new file mode 100644 index 0000000..fec34e2 --- /dev/null +++ b/org.glite.lb.doc/src/change_acl.tex @@ -0,0 +1,68 @@ +In order to change ACL for a job a special event \verb+ChangeACL+ is used. This +event can be logged by the job owner using the glite-lb-logevent command (see also +Sect.~\ref{cmdln_interface}). General template for changing the ACL is as follows: +\begin{verbatim} +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ + -j \ + --user_id \ + --user_id_type \ + --permission_type --operation +\end{verbatim} + +where + +\begin{tabularx}{\textwidth}{lX} +\verb'' & specifies the job to change \\ +\verb'' & specifies the user to use, can be either an X.500 name + (subject name) or a VOMS group (of the form :)\\ +\verb'' & \verb'0' or \verb'1', indicating \verb'user_id' + specifies X.500 name or VOMS group, respectively \\ +\verb'' & \verb'0' or \verb'1', indicating the user is + \textit{allowed} or \textit{denied}, respectively \\ +\verb'' & \verb'0' or \verb'1' indicating the record carried in + the event shall be added or removed, respectively from + the ACL \\ +\end{tabularx} + +Adding a user specified by her subject name to the ACL (\verb'user_id' = +subject name, \verb'user_id_type' = 0, \verb'permission_type' = 0, +\verb'operation' = 0): +\begin{verbatim} +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ + -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ + --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ + --user_id_type 0 --permission_type 0 --operation 0 +\end{verbatim} + +Removing a user specified by her subject name from the ACL (\verb'user_id' = +subject name, \verb'user_id_type' = 0, \verb'permission_type' = 0, +\verb'operation' = 1): + +\begin{verbatim} +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ + -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ + --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ + --user_id_type 0 --permission_type 0 --operation 1 +\end{verbatim} + +Adding a VOMS group to the ACL (\verb'user_id' = VOMS group, +\verb'user_id_type' = 1, \verb'permission_type' = 0, \verb'operation' = 0): + +\begin{verbatim} +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ + -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ + --user_id 'VOCE:/VOCE' \ + --user_id_type 1 --permission_type 0 --operation 0 +\end{verbatim} + +Denying a particular user from accessing information about the job, can be +combined e.g. with VOMS groups (\verb'user_id' = subject name, +\verb'user_id_type' = 0, \verb'permission_type' = 1, \verb'operation' = 0): + +\begin{verbatim} +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ + -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ + --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ + --user_id_type 0 --permission_type 1 --operation 0 +\end{verbatim} + diff --git a/org.glite.lb.doc/src/doxygen.sty b/org.glite.lb.doc/src/doxygen.sty new file mode 100644 index 0000000..90f368b --- /dev/null +++ b/org.glite.lb.doc/src/doxygen.sty @@ -0,0 +1,64 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{doxygen} +\RequirePackage{calc} +\RequirePackage{array} +%\pagestyle{fancyplain} +\newcommand{\clearemptydoublepage}{\newpage{\pagestyle{empty}\cleardoublepage}} +%\renewcommand{\chaptermark}[1]{\markboth{#1}{}} +%\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}} +%\lhead[\fancyplain{}{\bfseries\thepage}] +% {\fancyplain{}{\bfseries\rightmark}} +%\rhead[\fancyplain{}{\bfseries\leftmark}] +% {\fancyplain{}{\bfseries\thepage}} +%\rfoot[\fancyplain{}{\bfseries\scriptsize Generated on Tue Feb 22 11:20:54 2005 for Glite LB Client: C - Interface by Doxygen }]{} +%\lfoot[]{\fancyplain{}{\bfseries\scriptsize Generated on Tue Feb 22 11:20:54 2005 for Glite LB Client: C - Interface by Doxygen }} +%\cfoot{} +\newenvironment{CompactList} +{\begin{list}{}{ + \setlength{\leftmargin}{0.5cm} + \setlength{\itemsep}{0pt} + \setlength{\parsep}{0pt} + \setlength{\topsep}{0pt} + \renewcommand{\makelabel}{}}} +{\end{list}} +\newenvironment{CompactItemize} +{ + \begin{itemize} + \setlength{\itemsep}{-3pt} + \setlength{\parsep}{0pt} + \setlength{\topsep}{0pt} + \setlength{\partopsep}{0pt} +} +{\end{itemize}} +\newcommand{\PBS}[1]{\let\temp=\\#1\let\\=\temp} +\newlength{\tmplength} +\newenvironment{TabularC}[1] +{ +\setlength{\tmplength} + {\linewidth/(#1)-\tabcolsep*2-\arrayrulewidth*(#1+1)/(#1)} + \par\begin{tabular*}{\linewidth} + {*{#1}{|>{\PBS\raggedright\hspace{0pt}}p{\the\tmplength}}|} +} +{\end{tabular*}\par} +\newcommand{\entrylabel}[1]{ + {\parbox[b]{\labelwidth-4pt}{\makebox[0pt][l]{\textbf{#1}}\\}}} +\newenvironment{Desc} +{\begin{list}{} + { + \settowidth{\labelwidth}{40pt} + \setlength{\leftmargin}{\labelwidth} + \setlength{\parsep}{0pt} + \setlength{\itemsep}{-4pt} + \renewcommand{\makelabel}{\entrylabel} + } +} +{\end{list}} +\newenvironment{Indent} + {\begin{list}{}{\setlength{\leftmargin}{0.5cm}} + \item[]\ignorespaces} + {\unskip\end{list}} +\setlength{\parindent}{0cm} +\setlength{\parskip}{0.2cm} +\addtocounter{secnumdepth}{1} +\sloppy +\usepackage[T1]{fontenc} diff --git a/org.glite.lb.doc/src/doxyhack.tex b/org.glite.lb.doc/src/doxyhack.tex new file mode 100644 index 0000000..b349b55 --- /dev/null +++ b/org.glite.lb.doc/src/doxyhack.tex @@ -0,0 +1,31 @@ +% save previous definitions for use in new macros +\let\dsection=\section +\let\dsubsection=\subsection +\let\dsubsubsection=\subsubsection + +% change the sections definition to reflect the actual hierarchy +% - section is just one in each included file +\renewcommand{\section}[1]{\dsubsubsection{#1}} +% - subsections are for member section headings (constructors, data, ...) +\renewcommand{\subsection}[2]{\ifx*#1 +\dsubsubsection*{#2}\def\zbytek{} +\else +\dsubsubsection*{#1}\def\zbytek{#2}\fi +\zbytek} +% - subsubsections are for particular class members +\def\eatbraces#1]{} +\def\dosubsubsection#1{\par + \vskip 10pt\framebox{\begin{minipage}{\linewidth}{\hangindent=20pt\noindent\bf #1\par}\end{minipage}}\vskip-2pt} +\renewcommand{\subsubsection}[2]{\ifx*#1 + \dosubsubsection{#2}\def\zbytek{} +\else\ifx[#1 + \def\zbytek{\expandafter\dosubsubsection\eatbraces} +\else + \dosubsubsection{#1}\def\zbytek{#2} +\fi\fi +\zbytek} + +%\let\ddescription=\description +%\let\denddescription=\enddescription +%\renewenvironment{description}{\list{}{\labelwidth 5cm\leftmargin 3cm}}{\endlist} + diff --git a/org.glite.lb.doc/src/egee.cls b/org.glite.lb.doc/src/egee.cls new file mode 100644 index 0000000..886a74a --- /dev/null +++ b/org.glite.lb.doc/src/egee.cls @@ -0,0 +1,504 @@ +% egee.cls: +% +% $Id$ +% +% $Log$ +% Revision 1.13 2004/08/31 19:24:27 szamsu +% Fixing overfull problem in page headers. Saving the logo and reusing it later, instead of loading in again. +% +% Revision 1.12 2004/08/09 14:03:54 szamsu +% proper IST number +% +% Revision 1.11 2004/08/03 17:02:21 szamsu +% Information Society Infrastrcutures logo replacing the old IST logo +% +% Revision 1.10 2004/08/03 13:34:37 szamsu +% Removed 'compat2' option on geometry, because it has also specified +% 'scale{0.8,0.9}' for page size, which we define otherwise. Added the +% 'centering' and 'includeheadfoot' options, which were defined in +% 'compat2'. +% +% Revision 1.9 2004/07/09 16:06:52 leanne +% Removed the Lead partner which is not used in egee +% +% Revision 1.8 2004/06/03 09:56:11 leanne +% removed lead partner + +% Revision 1.8 2004/06/03 09:56:11 diana +% updated the front page +% +% Revision 1.7 2004/05/26 09:38:55 leanne +% Removed DocumentLink in pdfinfo - it was causing errors +% +% Revision 1.6 2004/05/26 08:36:58 leanne +% Updated IST number in template +% +% Revision 1.5 2004/05/24 13:25:04 diana +% added template for egee latex documents +% +% Revision 1.4 2004/05/17 10:56:51 diana +% added compat2 option to geometry and hypertex option to hyperref to get logo and links back on the page +% +% Revision 1.3 2004/02/18 18:08:48 leanne +% Modified Document identifiers to mauch the EGEE Word templates +% +% Revision 1.2 2004/02/18 17:23:21 leanne +% Changed Work Package to Activity. Included definition of Document Link. +% +% Revision 1.1.1.1 2004/02/18 11:17:44 leanne +% Initial version of EGGE LaTeX Style files based on the EDG LaTeX Style +% +% +% Revision 1.0 2004/02/17 leanne +% Took the datagrid.cls file and modified it for the EGEE project +% Original Authors: +% Frohner Akos +% Diana Bosio +% Paul Millar +% Thanks are due to Norman Gray +% +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{egee}[2002/06/20 EGEE LaTeX Class] +\typeout{EGEE LaTeX class -- 2002/06/13 Rock Lobster!} +% +%% Notes: This class file tries, as largely as possible, to copy the Microsoft +%% Word template document EDMS 2098656 v2.2. Differences and notes are listed +%% below: +%% o The Word Template uses 11pt for the main body, but 12 point +%% occasionally. Any such occurrence of 12pt is mapped into 11pt in this +%% class-file. +%% o This class inherits 11pt article. In that class Huge=30pt and +%% LARGE=22pt, which matches the required point-size for the title page. +%% o The parskip in the Word doc is exactly 1.4mm (0.7mm above and below). +%% Here we've taken the liberty of adding some glue to make things fit +%% better. +%% o The Word Template shows all the (sub)sections on the contents page in +%% capitals and subsubsections in italics. The LateX class doesn't. + +%% Interface - example of an option, should we want to use these later. +%\newif\ifmonotitle\monotitlefalse + +%\DeclareOption{mono}{\monotitletrue} + +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions + + +% Inherit! +\LoadClass[11pt]{article} + +% Necessary packages: +\RequirePackage{lastpage} +\RequirePackage{tabularx} +\RequirePackage{pslatex} +\RequirePackage{times} +\RequirePackage{verbatim} +\RequirePackage{geometry} +\RequirePackage{url} + +\usepackage[hang,bf,small]{caption} + +% +% We now define a new \if command to test for PDF being enabled. +% It is important because loading graphicx overrides the definition +% of \pdfoutput and sets it to true even when PDF is not enabled. +% Use \ifpdf instead of \ifx\pdfoutput\undefined hereafter. +% + +\newif\ifpdf +\ifx\pdfoutput\undefined + \pdffalse + % \typeout{PDF _not_ defined} +\else + \pdfoutput=1 + \pdftrue + % \typeout{PDF _is_ defined} +\fi + +\ifpdf + \usepackage[pdftex, + pdfpagemode={UseOutlines},bookmarks=true,bookmarksopen=true, + bookmarksopenlevel=0,bookmarksnumbered=true, + hypertexnames=false,colorlinks,linkcolor={blue}, + citecolor={blue},urlcolor={red}, + pdfstartview={FitV}]{hyperref} +\else + \usepackage[hypertex]{hyperref} +\fi + +\ifpdf + \usepackage[pdftex]{graphicx} + \pdfcompresslevel 9 + \pdfadjustspacing 1 +\else + \usepackage[dvips]{graphicx} +\fi + +\usepackage{color} + +\def\footsize{5mm} + +%% +%% PAGE GEOMETRY DEFINITIONS +%% +% From Template file +\geometry{centering,includeheadfoot} +\geometry{a4paper,top=12.5mm,headheight=12.5mm,headsep=5mm,foot=\footsize,footskip=13.3mm,bottom=12.5mm} +\geometry{right=25mm,left=25mm} + + +% APM -- I don't think these are right, my impression is above is correct +%\geometry{a4paper,margin=0.98in,headheight=0.72in} + + +%% +%% PAGE COLOUR DEFINITIONS +%% +\definecolor{blue}{rgb}{0.1,0.1,0.5} +\definecolor{lightgrey}{gray}{0.65} + + +% paulm's prefered name ... +\def\bibname{References} + +\setlength{\parindent}{0pt} +\setlength{\parskip}{1.4mm plus 0.4mm minus 0.2mm} + +\def\@defaultfooter{ + \def\@oddfoot{\vbox to \footsize {% + {\color{blue}\hrule width \textwidth height 1pt depth 0pt}% + \vfil + \small\hbox to \textwidth{\ISTNumber% + \hfil + \hbox{\colorbox{yellow}{\MakeUppercase{\@Dissemination}}}% + \hfil + \hbox{\thepage/\pageref{LastPage}}}% + }% + }% +} + + +\def\ps@title{% + \@defaultfooter + \def\@oddhead{\hbox to \textwidth{\LargeEGEELogo\hfil\ISTLogo}} +} + +\def\ps@headings{% + \@defaultfooter + \def\@oddhead{\vbox to \headheight{% +%\hrule width \textwidth height 1pt\relax + \vbox to 0.75\headheight{% + \hbox to \textwidth{% + \hbox to 0pt{\EGEELogo\hss}% + \hfil + \hbox to 8cm{% + \vbox to 0.75\headheight{% + \vfil + \parbox{8cm}{% + \centering\color{blue}% + \textbf{\MakeUppercase{\@title}}% +\ifx\@Subtitle\@empty\else + \par\textbf{\scriptsize\@Subtitle}% +\fi + }% + \vfil + }% + \hss}% + \hfil +%\hbox to 0pt{\vrule width 1pt height 10pt depth 0pt \hss}% +%% {\scriptsize\setlength{\parskip}{0pt}\setlength{\topsep}{0pt}% +%% % \vbox to 0.75\headheight{% +%% \parbox{4cm}{x% +%% \begin{flushright}% +%% \textit{Doc. Identifier}:\\ +%% \textbf{\@DocIdentifier}\\ +%% \vfil +%% \textit{Date}: \textbf{\@Date} +%% \end{flushright}% +%% }% +%% % }% +%% }% +\hbox to 0pt{\hss\vbox to 0.75\headheight{%\hrule +\tiny%\scriptsize +\parfillskip0pt +\leftskip 0pt plus 1fil +\parskip0ex +\textit{Doc.\ Identifier}: +\par +\textbf{\@DocIdentifier} +\vfil +\textit{Date}: \textbf{\@Date} +%\hrule +}}% +% \hbox to 4cm{\scriptsize +% \vbox to 0.75\headheight{% +% \parbox{4cm}{ +% \halign{\hfill####\cr +% \textit{Doc. Identifier}:\cr +% \textbf{\@DocIdentifier}\cr +% % \noalign{\vfil} +% \textit{Date}: \textbf{\@Date}\cr +% }}% +% \vfil +% }% +% }% + }% + }% +%\hrule width \textwidth height 1pt\relax + \vfil\vskip 2.5mm\relax + {\color{blue}\hrule width \textwidth height 1pt depth 0pt}% + }% + }% +} + +\pagestyle{headings} + +\setlength{\captionmargin}{1cm} + +% image file extensions respective to the output format +\ifpdf + \DeclareGraphicsExtensions{.jpg,.pdf,.png} + \pdfcompresslevel=9 +% \pdfinfo{ /Title (\@DocumentLink) } + \pdfinfo{ /Title (EGEE) } +\else + \DeclareGraphicsExtensions{.eps} +\fi + +\def\frontboxwidth{10.6cm}% + + + +%% +%% Define our title page +%% +\AtBeginDocument{ +\pagestyle{title}% +\hbox{}% Force top of page +\vfill +{\centering + \Huge\bf\textsf{\textcolor{blue}{EGEE}}\\[20mm]% + \LARGE\sc\textsf{\bf \@title}\\[5mm]% + \ifx\@Subtitle\@empty\else + \normalsize\textsf{\@Subtitle}\\[10mm]% + \fi + \ifx\@DeliverableId\@empty\else + \LARGE\sc\textsf{\bf \@DeliverableId}\\[5mm]% + \fi +}% +\vfill +\hbox to \textwidth{ + \hfil + \vbox{ + {\color{blue}\hrule width \frontboxwidth height 1mm depth 0pt} + \hbox to \frontboxwidth{\sf + \begin{tabularx}{\frontboxwidth}{l>{\raggedright\arraybackslash}X} + Document identifier: & \textbf{\@DocIdentifier}\\[3mm] + Date: & \textbf{\@Date}\\[3mm] + Activity:& \textbf{\@Activity}\\[3mm] + Document status: & \textbf{\@DocStatus}\\[3mm] + Document link:& \textbf{\@DocumentLink}\\[3mm] + \end{tabularx} + } + {\color{blue}\hrule width \frontboxwidth height 1mm depth 0pt} + } +} +\vfill +{\sf\underline{Abstract}: \@Abstract} +\vfill +\newpage % end of the first page +\pagestyle{headings} +\setcounter{tocdepth}{3} +} % End of AtBeginningDocument + + +% +% EGEE style small-capital section titles. +% +% The numbering is aligned with the WinWord style, +% although it is not common in the english typography... +% +\newcommand{\sectionbreak}{\newpage} +\renewcommand{\thesection}{\arabic{section}.} +\renewcommand{\thesubsection}{\thesection\arabic{subsection}.} +\renewcommand{\thesubsubsection}{\thesubsection\arabic{subsubsection}.} + +\renewcommand\section{\@startsection {section}{1}{\z@}% + {-3.5ex \@plus -1ex \@minus -.2ex}% + {2.3ex \@plus.2ex}% + {\normalfont\Large\bfseries\sffamily\scshape}} + +\renewcommand\subsection{\@startsection{subsection}{2}{\z@}% + {-3.25ex\@plus -1ex \@minus -.2ex}% + {1.5ex \@plus .2ex}% + {\normalfont\large\bfseries\sffamily\scshape}} +\renewcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}% + {-3.25ex\@plus -1ex \@minus -.2ex}% + {1.5ex \@plus .2ex}% + {\normalfont\normalsize\bfseries\sffamily\scshape}} + + + +%% APM NEED TO REDEFINE section +%\titleformat{\section}{\Large\bfseries\sffamily\scshape}{\thesection}{1em}{} +%\titlecontents{section} [2em] {\vspace*{4pt}} +% {\large \sc \bfseries \contentslabel{2em}} +% {\large \sc \bfseries \hspace*{-2em}} +% {\large \textbf{\titlerule*[1ex]{.}\contentspage}} [\vspace*{4pt}] + +%\titleformat{\subsection}{\large\bfseries\sffamily\scshape}{\thesubsection}{1em}{} +%\titlecontents{subsection} [5em] {} +% {\sc \contentslabel{3em}} +% {\sc \hspace*{-3em}} +% {\titlerule*[1ex]{.}\contentspage} + + +% +% common constants +% +\def\ISTNumber{INFSO-RI-508833} +\newsavebox{\@EGEELogo} +\savebox{\@EGEELogo}{\includegraphics[height=0.75\headheight]{egee}} +\def\EGEELogo{\usebox{\@EGEELogo}} +\def\LargeEGEELogo{\includegraphics[height=\headheight]{egee}} +\def\ISTLogo{\includegraphics[height=\headheight]{isi}} + +% +% parameters to be supplied by the author +% +\def\Subtitle#1{\gdef\@Subtitle{#1}} +\gdef\@Subtitle{\@latex@warning@no@line{No \noexpand\Subtitle given}} + +\def\DeliverableId#1{\gdef\@DeliverableId{#1}} +\gdef\@DeliverableId{\@latex@warning@no@line{No \noexpand\DeliverableId given}} + +\def\DocIdentifier#1{\gdef\@DocIdentifier{#1}} +\gdef\@DocIdentifier{\@latex@warning@no@line{No \noexpand\DocIdentifier given % + (e.g. EGEE-JRA1-TEC-edmsId-v0-1)}} + +\def\Date#1{\gdef\@Date{#1}} +\gdef\@Date{\@latex@warning@no@line{No \noexpand\Date given % + (e.g. 01/01/2004)}} + +\def\Activity#1{\gdef\@Activity{#1}} +\gdef\@Activity{\@latex@warning@no@line{No \noexpand\Activity given % + (e.g. JRA1 Middleware Engineering and Integration )}} + +\def\DocStatus#1{\gdef\@DocStatus{#1}} +\gdef\@DocStatus{\@latex@warning@no@line{No \noexpand\DocStatus given % + (e.g. DRAFT, WORKING, DELIVERED)}} + +\def\Dissemination#1{\gdef\@Dissemination{#1}} +\gdef\@Dissemination{\@latex@warning@no@line{No \noexpand\Dissemination given % + (e.g. PUBLIC, INTERNAL, ...)}} + +\def\DocumentLink#1{\gdef\@DocumentLink{#1}} +\gdef\@DocumentLink{\@latex@warning@no@line{No \noexpand\DocumentLink given % + (e.g. http://cern.ch)}} + +\long\def\Abstract#1{\gdef\@Abstract{#1}} +\gdef\@Abstract{\@latex@warning@no@line{No \noexpand\Abstract given}} + +%% +%% Define the abstract using an environment abstract + +% +% This will produce the mailto link in the PDF file +% +% +% We use the URL package, which does this nicely. The old way (\HTTP) was +% a bit buggy as it had problems with '~'s and '_'s +% +\urlstyle{sf} +\ifpdf + \newcommand{\Email}[1]{\href{mailto:#1}{<{#1}>}} + \newcommand{\HTTP}[1]{\href{#1}{\url{#1}}} +\else + \newcommand{\Email}[1]{\textsf{<{#1}>}} + \newcommand{\HTTP}[1]{\url{#1}} +\fi + + +% +% We now redifine \part and \section so that the table of contents +% has the sections/parts in upper case. +% +% Note: need to use \uppercase because \MakeUppercase is not robust +% +\def\@part[#1]#2{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{part}% + \addcontentsline{toc}{part}{\thepart\hspace{1em}\uppercase{#1}}% + \else + \addcontentsline{toc}{part}{\uppercase{#1}}% + \fi + {\parindent \z@ \raggedright + \interlinepenalty \@M + \normalfont + \ifnum \c@secnumdepth >\m@ne + \Large\bfseries \partname\nobreakspace\thepart + \par\nobreak + \fi + \huge \bfseries #2% + \markboth{}{}\par}% + \nobreak + \vskip 3ex + \@afterheading} + +\def\@sect#1#2#3#4#5#6[#7]#8{% + \ifnum #2>\c@secnumdepth + \let\@svsec\@empty + \else + \refstepcounter{#1}% + \protected@edef\@svsec{\@seccntformat{#1}\relax}% + \fi + \@tempskipa #5\relax + \ifdim \@tempskipa>\z@ + \begingroup + #6{% + \@hangfrom{\hskip #3\relax\@svsec}% + \interlinepenalty \@M #8\@@par}% + \endgroup + \csname #1mark\endcsname{\uppercase{#7}}% + \addcontentsline{toc}{#1}{% + \ifnum #2>\c@secnumdepth \else + \protect\numberline{\csname the#1\endcsname}% + \fi + \texorpdfstring{\uppercase{#7}}{#7}}% + \else + \def\@svsechd{% + #6{\hskip #3\relax + \@svsec #8}% + \csname #1mark\endcsname{\uppercase{#7}}% + \addcontentsline{toc}{#1}{% + \ifnum #2>\c@secnumdepth \else + \protect\numberline{\csname the#1\endcsname}% + \fi + \texorpdfstring{\uppercase{#7}}{#7}}}% + \fi + \@xsect{#5}} + +% \addcontentsline{toc} expands to \contentsline{NAME} +% which in turn expands to \l@NAME. So, to specify +% the table of contents, we must define \l@chapter, \l@section, +% \l@subsection, ... ; to specify the list of figures, we must define +% \l@figure; and so on. Most of these can be defined with the +% \@dottedtocline command, which produces a contents line with dots +% between the title and the page number. It works as follows: +% +% \@dottedtocline{LEVEL}{INDENT}{NUMWIDTH} +% LEVEL : An entry is produced only if LEVEL < or = value of +% 'tocdepth' counter. Note, \chapter is level 0, \section +% is level 1, etc. +% INDENT : The indentation from the outer left margin of the start of +% the contents line. +% NUMWIDTH : The width of a box in which the section number is to go, +% if TITLE includes a \numberline command. +% + +\def\l@part{\@dottedtocline{1}{4em}{2.0em}} +\def\l@subsection{\@dottedtocline{2}{1.5em}{2.3em}} +\def\l@subsubsection{\@dottedtocline{3}{3.8em}{3.2em}} +\def\l@paragraph{\@dottedtocline{4}{7.0em}{4.1em}} +\def\l@subparagraph{\@dottedtocline{5}{10em}{5em}} + diff --git a/org.glite.lb.doc/src/frontmatter.tex b/org.glite.lb.doc/src/frontmatter.tex new file mode 100644 index 0000000..a3c0931 --- /dev/null +++ b/org.glite.lb.doc/src/frontmatter.tex @@ -0,0 +1,39 @@ +\begin{center} +{\bf Delivery Slip} +\end{center} +\begin{tabularx}{\textwidth}{|l|l|l|X|X|} +\hline + & {\bf Name} & {\bf Partner} & {\bf Date} & {\bf Signature} \\ +\hline +{\bf From} & & & & \\ +\hline +{\bf Reviewed by} & & & & \\ + +\hline +{\bf Approved by} & & & & \\ +\hline +\end{tabularx} + +\begin{center} +{\bf Document Change Log} +\end{center} + +\begin{tabularx}{\textwidth}{|l|l|X|X|} +\hline +{\bf Issue } & {\bf Date } & {\bf Comment } & {\bf Author } \\ \hline + +\hline +\end{tabularx} + +\begin{center} +{\bf Document Change Record} +\end{center} + +\begin{tabularx}{\textwidth}{|l|l|X|} +\hline +{\bf Issue } & {\bf Item } & {\bf Reason for Change } \\ \hline + +\hline +\end{tabularx} + +\input{copyright} diff --git a/org.glite.lb.doc/src/interaction.tex b/org.glite.lb.doc/src/interaction.tex new file mode 100644 index 0000000..376d962 --- /dev/null +++ b/org.glite.lb.doc/src/interaction.tex @@ -0,0 +1,44 @@ +The main \LB\ functionality is keeping track of jobs managed by +the Workload Management System otherwise. +Therefore its basic usage is done internally by the WMS components. +However, the query and notification interface is completely available +to user-level applications. Upto limited extent (two event types) +this holds for the event-logging interface too. + +\subsubsection{Event sources} +\LB\ events are generated by the following WMS components: +\begin{description} +\item[User Interface] registers the job with \LB\ and provides details +on transfer of the job to the resource broker. +\item[Resource Broker,] consisting of several WMS components, +logs various events as the job is passed among these components, +as well as other important job-related information (\eg\ the chosen +destination Computing Element). +\item[Computing Element,] via the Job Wrapper script, provides the immediate +information on job execution. +\end{description} +Besides these WMS components the job payload may also log UserTag events +(see Sect.~\ref{log_usertag}) containing arbitrary user information. + +Checkpointable jobs also use \LB\ to keep track of the job progress. +This is done internally by the checkpoint support library. + +Finally, changes of job access control lists are done by logging +another event. This may be done directly by the user or using the WMS +user interface. + +\subsubsection{Queries} + +The \LB\ queries with a~user-visible output +are executed from within WMS User Interface +commands glite-job-status and glite-job-logging-info. + +Besides those several WMS components use \LB\ internally to query +information on job status which is relevant for their processing. + +\subsubsection{Notifications} + +Notifications on job state change are used by WMS GUI +to monitor the state of jobs periodically. + + diff --git a/org.glite.lb.doc/src/notification_api.tex b/org.glite.lb.doc/src/notification_api.tex new file mode 100644 index 0000000..a236851 --- /dev/null +++ b/org.glite.lb.doc/src/notification_api.tex @@ -0,0 +1,126 @@ +The purpose of this section is demonstrating the usage of the \LB\ notification API. Two examples of basic API usage are given. + + +\subsubsection{Registering and receiving notification} + +The following example registers on \LB\ server to receive notifications triggered by events belonging to job with \verb'jobid' and waits for notification until \verb'timeout'. +The code assumes the user to prepare a~reasonable value in \verb'jobid' +(\ie\ identifying an existing job). + +%The glite-lb-bkserverd and glite-lb-notif-interlogd daemons have to be running. The first one user registers to, the second one delivers notifications to the example program (as described in \ref{notification}). + +\begin{verbatim} + #include + #include + #include + #include + #include + + #include "glite/lb/context.h" + #include "glite/lb/lb_gss.h" + #include "glite/lb/notification.h" + + /* jobid magically appears here */ + char *jobid; + + edg_wll_Context ctx; + edg_wll_QueryRec **conditions; + edg_wll_NotifId notif_id = NULL, recv_notif_id = NULL; + edg_wlc_JobId my_jobId = NULL; + edg_wll_JobStat stat; + time_t valid; + struct timeval timeout = {220, 0}; + ... + + edg_wll_InitContext(&ctx); + + memset(&stat, 0, sizeof(stat)); + + conditions = (edg_wll_QueryRec **)calloc(2,sizeof(edg_wll_QueryRec *)); + conditions[0] = (edg_wll_QueryRec *)calloc(2,sizeof(edg_wll_QueryRec)); + + edg_wlc_JobIdParse(jobid, &my_jobId); + + conditions[0][0].attr = EDG_WLL_QUERY_ATTR_JOBID; + conditions[0][0].op = EDG_WLL_QUERY_OP_EQUAL; + conditions[0][0].value.j = my_jobId; + + /* register notification on BK server */ + if (edg_wll_NotifNew(ctx, conditions, -1, NULL, ¬if_id, &validity)) + goto error; + + /* the ID string my be used to receive notifications */ + /* from another computer later on */ + printf("notification ID: %s\n", edg_wll_NotifIdUnparse(notif_id)); + + if (edg_wll_NotifReceive(ctx, -1, &timeout, &status, &recv_notif_id)) + /* timeout or error */ + goto error; + else { + /* notification arrived */ + /* check recv_notif_id if you have registered more notifications */ + /* to know which one you received. If you have just this one */ + /* do not bother. */ + + printf("Status of my job is: %s\n", edg_wll_StatToString(stat.state)); + edg_wll_FreeStatus(&stat); + edg_wll_NotifIdFree(recv_notif_id); + } + + /* Release registration on BK server. Don't do this if notif_id is reused. */ + edg_wll_NotifDrop(ctx, notif_id); + + edg_wll_NotifIdFree(notif_id); + edg_wll_NotifCloseFd(ctx); + + ... + +error: + /* clean-up */ + ... + +\end{verbatim} + +First of all the context is initialised. During this procedure user's credentials are loaded (see \ref{cmdln_interface} for information on environmental variables pointing to user's X509 credentials). + +Then conditions under which notifications are sent are set. In this example, user is notified every time when event with given jobId is logged to \LB\ server. For more complicated conditions, please, consider the conditions limitations mentioned in \ref{notification}. + +Afterwards, a new registration is created and a unique notification ID is +returned. +Notifications are recieved with the \verb'edg_wll_NotifReceive' call. +If no notification is ready for +delivery, the call waits until some notification arrival or timeout. + +If user does not want to receive notifications any more, \verb'edg_wll_NotifDrop' call removes the registration for notifications from \LB server. + + +\subsubsection{Changing destination for notifications} + +The second example illustrates how to receive notifications from different host or different application. + +Let us suppose that user is registered for receiving notifications on \LB\ server. She obtained a notification ID and information how long this registration will be valid as described in the previous example but she did not delete registration with \verb'edg_wll_NotifDrop'. + +If the registration is still valid, she can start new client for receiving notifications, even from different machine, using notification ID returned during registration in previous step. + +The sequence of function calls (without catching errors) would be as follows: + +\begin{verbatim} + edg_wll_NotifId nid; + char *ns; // notification ID string returned + // in previous example + ... + edg_wll_NotifIdParse(ns, &nid); + edg_wll_NotifBind(ctx, nid, -1, NULL, &valid); + + /* prolong the registration validity if necessary */ + if (...validity close to expire...) + edg_wll_NotifRefresh(ctx, nid, &valid); + + edg_wll_NotifReceive(ctx, -1, &timeout, &status, &recv_notif_id); + ... +\end{verbatim} + +The call \verb'edg_wll_NotifReceive' will return any notification +that was generated while there was no listening client for it. +If there are none, it will wait for new notifications as in the previous +example. -- 1.8.2.3