From 6b148d1ed8d5a3f63847e39386a69b27cd9c91a6 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ale=C5=A1=20K=C5=99enek?= Date: Wed, 3 Aug 2005 09:30:33 +0000 Subject: [PATCH] Merged the release 1.0 branch --- org.glite.lb.client-interface/Makefile | 8 +- org.glite.lb.client-interface/build.xml | 6 + org.glite.lb.client-interface/interface/CountRef.h | 31 +- org.glite.lb.client-interface/interface/Event.h.T | 147 ++++- org.glite.lb.client-interface/interface/Job.h | 237 +++++--- .../interface/JobStatus.h.T | 216 +++++-- .../interface/LoggingExceptions.h | 132 ++++- .../interface/Notification.h | 12 +- .../interface/ServerConnection.h | 655 +++++++++++++++++---- org.glite.lb.client-interface/interface/consumer.h | 197 ++++--- org.glite.lb.client-interface/interface/context.h | 64 +- org.glite.lb.client-interface/interface/events.h.T | 47 +- .../interface/jobstat.h.T | 12 +- .../interface/notification.h | 59 +- org.glite.lb.client-interface/interface/notifid.h | 74 ++- .../interface/producer.h.T | 101 ++-- .../interface/statistics.h | 12 +- .../project/configure.properties.xml | 40 +- org.glite.lb.client/Makefile | 3 +- org.glite.lb.client/examples/change_acl.c | 78 +++ org.glite.lb.client/examples/job_log.c | 7 +- org.glite.lb.client/src/ServerConnection.cpp | 61 +- org.glite.lb.client/src/connection.c | 40 +- org.glite.lb.common/build.xml | 6 + org.glite.lb.common/interface/log_proto.h | 1 - org.glite.lb.common/src/context.c | 1 + org.glite.lb.common/src/events.c.T | 22 +- org.glite.lb.common/src/param.c | 80 +-- org.glite.lb.logger/build.xml | 6 + org.glite.lb.logger/src/event_store.c | 88 ++- org.glite.lb.server-bones/Makefile | 8 +- org.glite.lb.server/Makefile | 10 +- org.glite.lb.server/build.xml | 6 + .../project/configure.properties.xml | 7 + org.glite.lb.server/src/dump.c | 20 +- org.glite.lb.server/src/server_state.c | 2 +- org.glite.lb.server/src/srv_purge.c | 3 +- 37 files changed, 1905 insertions(+), 594 deletions(-) create mode 100644 org.glite.lb.client/examples/change_acl.c diff --git a/org.glite.lb.client-interface/Makefile b/org.glite.lb.client-interface/Makefile index f4fc58a..fd3191a 100644 --- a/org.glite.lb.client-interface/Makefile +++ b/org.glite.lb.client-interface/Makefile @@ -20,7 +20,8 @@ AT3=perl -I${top_srcdir}/project ${top_srcdir}/project/at3 STAGETO=include/${globalprefix}/${lbprefix} STATIC_H=consumer.h context.h dump.h load.h notification.h notifid.h purge.h \ Notification.h CountRef.h Job.h LoggingExceptions.h ServerConnection.h \ - consumer_fake.h producer_fake.h statistics.h + statistics.h +FAKE_H=consumer_fake.h producer_fake.h GEN_H=events.h jobstat.h producer.h Event.h JobStatus.h interface_version.h @@ -39,7 +40,7 @@ check: interface_version.h: ${top_srcdir}/project/version.properties echo "#define GLITE_LB_CLIENT_INTERFACE \"${version}\"" >$@ stage: generate - $(MAKE) install PREFIX=${top_srcdir}/${stagedir} + $(MAKE) install PREFIX=${top_srcdir}/${stagedir} DOSTAGE=yes dist: distsrc distbin @@ -65,6 +66,9 @@ install: generate doc install -m 644 ${top_srcdir}/LICENSE ${PREFIX}/share/doc/${package}-${version} cd ${top_srcdir}/interface && install -m 644 ${STATIC_H} ${PREFIX}/${STAGETO} cd ${top_srcdir}/doc && cp -r C CPP ${PREFIX}/share/doc/${package}-${version} + if [ x${DOSTAGE} = xyes ]; then \ + cd ${top_srcdir}/interface && install -m 644 ${FAKE_H} ${PREFIX}/${STAGETO} ; \ + fi clean: rm -f *.h diff --git a/org.glite.lb.client-interface/build.xml b/org.glite.lb.client-interface/build.xml index 64da40e..d389be7 100755 --- a/org.glite.lb.client-interface/build.xml +++ b/org.glite.lb.client-interface/build.xml @@ -20,6 +20,12 @@ Revision history: $Log$ + Revision 1.7 2005/05/26 15:13:43 zurek + inserted module.build.file + + Revision 1.6.2.1 2005/02/12 01:38:33 glbuild + Changed start time + Revision 1.6 2004/10/18 19:16:09 zsalvet RPM descriptions diff --git a/org.glite.lb.client-interface/interface/CountRef.h b/org.glite.lb.client-interface/interface/CountRef.h index 462800d..13250ee 100644 --- a/org.glite.lb.client-interface/interface/CountRef.h +++ b/org.glite.lb.client-interface/interface/CountRef.h @@ -13,21 +13,35 @@ EWL_BEGIN_NAMESPACE +/** Class implementing simple reference counting mechanism. + * + * This class is used instead of simple pointers to enable sharing of + * objects using simple reference counting mechanism. It encapsulates + * the given (pointer to) object and remembers the number of + * references to it. Taking and getting rid of the reference to + * encapsulated object is explicit by calling member functions use() + * and release(). + */ template class CountRef { public: - CountRef(void *); + CountRef(void *); // CountRef(void *,void (*)(void *)); - void use(void); + void use(void); void release(void); - void *ptr; + void *ptr; /**< Pointer to the encapsulated object. */ + private: int count; // void (*destroy)(void *); }; +/** + * Encapsulate the given object and set reference count to 1. + * + */ template CountRef::CountRef(void *p) { @@ -35,6 +49,12 @@ CountRef::CountRef(void *p) count = 1; } +/** Decrease the reference count, possibly deallocating the + * encapsulated object. + * + * This method should be called when the holder no longer plans to use + * the encapsulated object, instead of deleting it. + */ template void CountRef::release(void) { @@ -44,6 +64,11 @@ void CountRef::release(void) } } +/** Increase the number of references to the object. + * + * This method should be called every time the pointer (ie. this + * instance) is copied. + */ template void CountRef::use(void) { diff --git a/org.glite.lb.client-interface/interface/Event.h.T b/org.glite.lb.client-interface/interface/Event.h.T index 29834d3..714a7c0 100644 --- a/org.glite.lb.client-interface/interface/Event.h.T +++ b/org.glite.lb.client-interface/interface/Event.h.T @@ -25,17 +25,25 @@ EWL_BEGIN_NAMESPACE +/** Class representing one event in the L&B database. + * + * This class represents a L&B event, which is basically list of + * attribute -- value pairs. For each particular event type (returned + * by name()) there is a list of allowed attributes (returned by + * getAttrs()). The Event class provides methods for reading these + * attributes, but no means of changing the + * event are provided; this class is used as a result of L&B queries. + */ class Event { friend class Job; friend class ServerConnection; friend class CountRef; public: - /** Event type codes. - * Identify which of the event fields are valid. + /** Event type codes + * identify which of the event fields are valid. */ - enum Type { - UNDEF = 0, + UNDEF = 0, /**< Undefined event type. */ @@@{ for my $e ($event->getTypesOrdered) { my $u = uc $e; @@ -43,10 +51,15 @@ public: gen "\t\t$u,\t/**< $c */\n"; } @@@} - TYPE_MAX + TYPE_MAX /**< Limit for checking type validity. */ }; - /** Event attribute symbolic identifier. */ + /** Event attribute symbolic identifier. + * These symbols provide symbolic names for event + * attributes. In braces are shown the event types for which the + * attribute is defined, for each event type the attribute + * meaning is described. + */ enum Attr { @@@{ for (sort {$a cmp $b} getAllFields $event) { @@ -59,14 +72,15 @@ public: selectType $event $t; my $cc = getFieldComment $event $_; $t = 'common' if $t eq '_common_'; - $c .= "\t * $t: $cc\n"; + $c .= "\t * \\n\[$t\] $cc\n"; } $c .= "\t */\n"; gen "$c\t\t$u,\n"; } @@@} - ATTR_MAX + ATTR_MAX /**< Limit for checking attribute code + validity. */ }; @@@{ @@ -75,10 +89,12 @@ public: my $ff; my $ut; my $utf; + my $fc; if ($t eq '_common_') { $ff = $f; $ut = ''; $utf = ''; + $fc = ''; } else { selectType $event $t; @@ -86,9 +102,11 @@ public: $ff = getField $event; $ut = uc $t . '_'; $utf = ucfirst $t; + $fc = $event->getFieldComment($f); } if ($ff->{codes}) { gen qq{ +! /** $fc */ ! enum ${utf}Code \{ }; for (@{$ff->{codes}}) { @@ -104,38 +122,117 @@ public: } @@@} - enum AttrType { INT_T, STRING_T, TIMEVAL_T, PORT_T, LOGSRC_T, JOBID_T, NOTIFID_T }; + /** Symbolic names for types of attribute values. */ + enum AttrType { INT_T, /**< Integer value. */ + STRING_T, /**< String value. */ + TIMEVAL_T, /**< Time value (ie. struct + timeval). */ + PORT_T, /**< Service port (integer). */ + LOGSRC_T, /**< Source of the event + (integer). */ + JOBID_T, /**< JobId value. */ + NOTIFID_T /**< NotifId value. */ + }; - Type type; + Type type; /**< Type of the event as defined by Type. */ + /** Default constructor. + * + * Initializes an empty event. + */ Event(void); + + /** Constructor from corresponding C type. + * + * Initializes the object from the corresponding C struct, in + * fact holding the pointer to it. + */ Event(edg_wll_Event *); + + /** Copy constructor. + * + * Creates a copy of the object by sharing the C struct + * with the original. + */ Event(const Event &); + + /** Destructor. + * + * Releases the C struct (possibly deallocating it). + */ ~Event(void); - /** Assign new Event to an existing instance. */ + /** Assign new Event to an existing instance. + * + * The original data are released and new ones are made + * accessible. + * \returns Reference to this object. + */ Event & operator= (const Event &); - /** String representation of the event type */ + /** String representation of the event type. + * + * Returns string representing the event type. + * \returns Name of the event. + * \throw Exception Invalid event type. + */ const std::string & name(void) const; - /** Retrieve integer attribute */ - int getValInt(Attr) const; - - /** Retrieve string attribute */ - std::string getValString(Attr) const; + /** Retrieve integer attribute. + * + * Retrieves value for attributes of integer type. + * \param[in] name Name of the attribute to retrieve. + * \returns Integer value of the attribute. + * \throw Exception Invalid event type or attribute not + * defined for this event. + */ + int getValInt(Attr name) const; + + /** Retrieve string attribute. + * + * Retrieves value for attributes of string type. + * \param[in] name Name of the attribute to retrieve. + * \returns String value of the attribute. + * \throw Exception Invalid event type or attribute not + * defined for this event. + */ + std::string getValString(Attr name) const; - /** Retrieve time attribute */ - struct timeval getValTime(Attr) const; + /** Retrieve time attribute. + * + * Retrieves value for attributes of timeval type. + * \param[in] name Name of the attribute to retrieve. + * \returns struct timeval value of the attribute. + */ + struct timeval getValTime(Attr name) const; - /** Retrieve jobid attribute */ - const glite::wmsutils::jobid::JobId getValJobId(Attr) const; - - /** Attribute name */ - const std::string & getAttrName(Attr) const; + /** Retrieve jobid attribute + * + * Retrieves value for attributes of JobId type. + * \param[in] name Name of the attribute to retrieve. + * \returns JobId value of the attribute. + * \throw Exception Invalid event type or attribute not + * defined for this event. + */ + const glite::wmsutils::jobid::JobId getValJobId(Attr name) const; + + /** Attribute name. + * + * Retrieves string representation of the attribute name. + * \param[in] name Symbolic name of the attribute. + * \returns String name of the attribute. + * \throw Exception Invalid event type or attribute not + * defined for this event. + */ + const std::string & getAttrName(Attr name) const; - /** List of attributes and types valid for this instance */ + /** List of attributes and types valid for this instance. + * + * Retrieves description of all attributes defined for this event. + * \returns Vector of Attr -- AttrType pairs. + * \throw Exception Invalid event type. + */ const std::vector > & getAttrs(void) const; private: diff --git a/org.glite.lb.client-interface/interface/Job.h b/org.glite.lb.client-interface/interface/Job.h index 58a8e91..9419066 100644 --- a/org.glite.lb.client-interface/interface/Job.h +++ b/org.glite.lb.client-interface/interface/Job.h @@ -17,100 +17,169 @@ EWL_BEGIN_NAMESPACE -/** L&B job. +/** Class encapsulating the job info stored in the L&B database. * - * Implementation of L&B job-specific calls. - * Connection to the server is maintained transparently. + * This class is the primary interface for getting information about + * jobs stored in the L&B database. It is constructed from known job + * id, which uniquely identifies the job as well as the bookkeeping + * server where the job data is stored. The Job class provides methods + * for obtaining the data from the bookkeeping server and for setting + * various parameters of the connection to the bookkeeping server. + * + * All query methods have their counterpart in C functions taking + * taking edg_wll_Context and edg_wll_JobId as their first parameters + * (in fact, those functions are used to do the actual work). */ - class Job { public: - Job(void); - Job(const glite::wmsutils::jobid::JobId &); - ~Job(); - - /** Assign new JobId to an existing instance. - * Connection to server is preserved if possible. - */ + /** Default constructor. + * + * Initializes the job as empty, not representing anything. + */ + Job(void); + + /** Constructor from job id. + * + * Initializes the job to obtain information for the given job id. + * \param[in] jobid The job id of the job this object will + * represent. + * \throws Exception Could not copy the job id. + */ + Job(const glite::wmsutils::jobid::JobId &jobid); + + + /** Destructor. + * + * All the actual work is done by member destructors, namely ServerConnection. + */ + ~Job(); - Job & operator= (const glite::wmsutils::jobid::JobId &); + /** Assign new job id to an existing instance. + * + * Redirect this instance to obtain information about + * different job; connection to the server is preserved, if + * possible. + * \param[in] jobid New job id. + * \returns Reference to this object. + * \throws Exception Could not copy the job id. + */ + Job & operator= (const glite::wmsutils::jobid::JobId &jobid); -/** - * Status retrieval bitmasks. Used ORed as Job::status() argument, - * determine which status fields are actually retrieved. - */ - static const int STAT_CLASSADS; /**< various job description fields */ - static const int STAT_CHILDREN; /**< list of subjob JobId's */ - static const int STAT_CHILDSTAT; /**< apply the flags recursively to subjobs */ + /* + * Status retrieval bitmasks. Used ORed as Job::status() argument, + * determine which status fields are actually retrieved. + */ + static const int STAT_CLASSADS; /**< Include the job + * description in the + * query result. */ + static const int STAT_CHILDREN; /**< Include the list of + * subjob id's in the + * query result. */ + static const int STAT_CHILDSTAT; /**< Apply the flags + * recursively to + * subjobs. */ - /** Return job status */ - JobStatus status(int) const; + /** Return job status. + * + * Obtain the job status (as JobStatus) from the bookkeeping + * server. + * \param[in] flags Specify details of the query. + * \returns Status of the job. + * \throws Exception Could not query the server. + * \see STAT_CLASSADS, STAT_CHILDREN, STAT_CHILDSTAT + */ + JobStatus status(int flags) const; - /** Return all events corresponding to this job */ - void log(std::vector &) const; - const std::vector log(void) const; + /** Return all events corresponding to this job + * + * Obtain all events corresponding to the job that are stored + * in the bookkeeping server database. The maximum number of + * returned events can be set by calling setParam(). + * \param[out] events Vector of events (of type Event). + * \throws Exception Could not query the server. + */ + void log(std::vector &events) const; + + /** Return all events corresponding to this job + * + * Obtain all events corresponding to the job that are stored + * in the bookkeeping server database. The maximum number of + * returned events can be set by calling setParam(). + * \returns Vector of events (of type Event). + * \throws Exception Could not query the server. + */ + const std::vector log(void) const; - /** Return last known address of a listener associated to the job. - * \param name IN name of the listener - * \return hostname and port number - */ - const std::pair queryListener(const std::string & name) const; + /** Return last known address of a listener associated to the job. + * + * Obtains the information about last listener that has been + * registered for this job in the bookkeeping server database. + * \param[in] name Name of the listener. + * \returns Hostname and port number of the registered + * listener. + * \throws Exception Could not query the server. + */ + const std::pair queryListener(const std::string &name) const; - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, int val); - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, const std::string val); - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, const struct timeval &val); - - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return integer value of the parameter - */ - int getParamInt(edg_wll_ContextParam ctx) const; - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return string value of the parameter - */ - std::string getParamString(edg_wll_ContextParam ctx) const; - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return timeval value of the parameter - */ - struct timeval getParamTime(edg_wll_ContextParam ctx) const; + /** + * Manipulate LB parameters. + * + * This method sets integer typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, int val); + + /** + * Manipulate LB parameters. + * + * This method sets string typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, const std::string val); + + /** + * Manipulate LB parameters. + * + * This method sets timeval typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, const struct timeval &val); + + /** + * Get LB parameters. + * + * Obtain value of the named integer parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + int getParamInt(edg_wll_ContextParam ctx) const; + + /** + * Get LB parameters. + * + * Obtain value of the named string parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + std::string getParamString(edg_wll_ContextParam ctx) const; + + /** + * Get LB parameters. + * + * Obtain value of the named timeval parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + struct timeval getParamTime(edg_wll_ContextParam ctx) const; private: ServerConnection server; diff --git a/org.glite.lb.client-interface/interface/JobStatus.h.T b/org.glite.lb.client-interface/interface/JobStatus.h.T index 8b63de1..f183a33 100644 --- a/org.glite.lb.client-interface/interface/JobStatus.h.T +++ b/org.glite.lb.client-interface/interface/JobStatus.h.T @@ -19,18 +19,26 @@ EWL_BEGIN_NAMESPACE; -/** - * Description of job status. - * The status is computed from a sequence of logged events +/** Class representing status of job. + * + * This class is used to represent all information about the job status + * as computed and stored in the bookkeeping server's database. Job + * status is, like Event, list of attribute -- value pairs. One of the + * attributes is the job's state as seen by the L&B, ie. something + * like RUNNING or * DONE, other attributes contain + * more information about the job. + * + * The JobStatus class provides methods for reading values of these + * attributes and it is used as a result of server queries. */ - - class JobStatus { friend class Job; friend class CountRef; public: + + /** Symbolic names of job states. */ enum Code { - UNDEF = 0, /**< indicates invalid, i.e. uninitialized instance */ + UNDEF = 0, /**< Indicates invalid, i.e. uninitialized instance. */ @@@{ for my $stat ($status->getTypesOrdered) { @@ -41,9 +49,14 @@ public: }; } @@@} - CODE_MAX + CODE_MAX /**< Limit for range checking. */ }; + /** Symbolic names of attributes. + * + * These constants are used for naming individual attributes + * when invoking their access methods. + */ enum Attr { @@@{ selectType $status '_common_'; @@ -56,7 +69,7 @@ public: gen "\t/** $f->{comment} */\n\t\t$u,\n"; } @@@} - ATTR_MAX + ATTR_MAX /**< Limit for range checking. */ }; @@@{ @@ -80,61 +93,176 @@ public: } } @@@} - enum AttrType { INT_T, - STRING_T, - TIMEVAL_T, - BOOL_T, - JOBID_T, - INTLIST_T, - STRLIST_T, - TAGLIST_T, - STSLIST_T + /** Symbolic names of attribute types. + * + * These constants are used to name the various attribute + * types. + */ + enum AttrType { INT_T, /**< Integer type. */ + STRING_T, /**< String type. */ + TIMEVAL_T, /**< struct timeval type. */ + BOOL_T, /**< Boolean type (true or false). */ + JOBID_T, /**< Job id type. */ + INTLIST_T, /**< List of integer values. */ + STRLIST_T, /**< List of string values. */ + TAGLIST_T, /**< List of user tags. */ + STSLIST_T /**< List of states. */ }; - /** Numeric status code */ + /** Numeric status code. + * + * This code represents the state of the job. + * \see Code. + */ Code status; - /** String representation of the status code */ + /** Get state name. + * + * Returns string representation of the job's state. + */ const std::string & name(void) const; - /** Retrieve integer attribute */ - int getValInt(Attr) const; + /** Access method for attribute values. + * + * Retrieve integer value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + int getValInt(Attr name) const; - /** Retrieve string attribute */ - std::string getValString(Attr) const; + /** Access method for attribute values. + * + * Retrieve string value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + std::string getValString(Attr name) const; - /** Retrieve time attribute */ - struct timeval getValTime(Attr) const; + /** Access method for attribute values. + * + * Retrieve struct timeval value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + struct timeval getValTime(Attr name) const; - /** Retrieve jobid attribute */ - const glite::wmsutils::jobid::JobId getValJobId(Attr) const; + /** Access method for attribute values. + * + * Retrieve JobId value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const glite::wmsutils::jobid::JobId getValJobId(Attr name) const; - /** Retrieve bool attribute */ - bool getValBool(Attr) const; + /** Access method for attribute values. + * + * Retrieve bool value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + bool getValBool(Attr name) const; - /** Retrieve int list attribute */ - const std::vector getValIntList(Attr) const; + /** Access method for attribute values. + * + * Retrieve integer values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValIntList(Attr name) const; - /** Retrieve string list attribute */ - const std::vector getValStringList(Attr) const; + /** Access method for attribute values. + * + * Retrieve string values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValStringList(Attr name) const; - /** Retrieve tag list attribute */ - const std::vector > getValTagList(Attr) const; + /** Access method for attribute values. + * + * Retrieve user tags values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector > getValTagList(Attr name) const; - /** Retrieve job status list attribute */ - const std::vector getValJobStatusList(Attr) const; + /** Access method for attribute values. + * + * Retrieve status values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValJobStatusList(Attr name) const; - /** Attribute name */ - const std::string& getAttrName(Attr) const; + /** Get name of attribute. + * + * Retrieve string representation of symbolic name of attribute. + * \param[in] name Symbolic name of attribute. + * \returns Name of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::string& getAttrName(Attr name) const; - /** List of attributes and types valid for this instance */ + /** List of attributes and their types valid for this + * instance. + * + * Returns the vector of (attribute, attribute type) pairs + * that this instance of JobStatus contains. + * \returns List of attributes. + */ const std::vector >& getAttrs(void) const; + /** Default constructor. + * + * Initializes an empty instance. + */ JobStatus(void); - JobStatus(const JobStatus &); - JobStatus & operator=(const JobStatus &); - JobStatus(const edg_wll_JobStat &); - JobStatus & operator=(const edg_wll_JobStat&); + + /** Copy constructor. + * + * Creates identical copy of the original object. + * The underlying C struct edg_wll_JobStatus is shared using + * the CountRef mechanism. + * \param[in] orig Original. + */ + JobStatus(const JobStatus &orig); + + /** Assignment operator. + * + * Creates identical copy of the original object. + * The underlying C struct edg_wll_JobStatus is shared using + * the CountRef mechanism. + * \param[in] orig Original. + */ + JobStatus & operator=(const JobStatus &orig); + + /** Constructor from the C type. + * + * Encapsulates the given struct. + * \param[in] src C struct that holds the status. + */ + JobStatus(const edg_wll_JobStat &src); + + /** Assignment from the C type. + * + * Encapsulates the given struct. + * \param[in] src C struct that holds the status. + */ + JobStatus & operator=(const edg_wll_JobStat& src); + + /** Destructor. + * + * Releases the encapsulated C struct. + */ virtual ~JobStatus(); protected: diff --git a/org.glite.lb.client-interface/interface/LoggingExceptions.h b/org.glite.lb.client-interface/interface/LoggingExceptions.h index 15ce0ab..b44985f 100644 --- a/org.glite.lb.client-interface/interface/LoggingExceptions.h +++ b/org.glite.lb.client-interface/interface/LoggingExceptions.h @@ -13,23 +13,52 @@ EWL_BEGIN_NAMESPACE +/** Base class for all exceptions thrown by the L&B C++ classes. + * + * This class serves as a common base for all exceptions thrown by the + * L&B C++ API classes. In case when the exception is constructed from + * another exception (creating chained exception list), the error + * message is created by concatenating the error message of the + * original exception and the new error message. All the other + * functionality (printing error message, logging it, printing stack + * trace) is inherited from the base class glite::wmsutils::exception::Exception. + */ class Exception: public glite::wmsutils::exception::Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + */ Exception(const std::string& source, int line_number, const std::string& method, int code, const std::string& exception) : glite::wmsutils::exception::Exception(source, - line_number, - method, - code, - "glite::lb::Exception") + line_number, + method, + code, + "glite::lb::Exception") { error_message = exception; }; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + * \param[in] exc Originally raised exception. + */ Exception(const std::string& source, int line_number, const std::string& method, @@ -37,18 +66,33 @@ public: const std::string& exception, const glite::wmsutils::exception::Exception &exc) : glite::wmsutils::exception::Exception(source, - line_number, - method, - code, - "glite::lb::Exception") + line_number, + method, + code, + "glite::lb::Exception") { error_message = exception + ": " + exc.what(); }; }; +/** Exception encapsulating error states originating in the L&B. + * + * This class is simple child of the base Exception class, adding no + * new functionality. Its purpose is to differentiate the error + * conditions originating in the L&B subsystem from other errors (such + * as system ones). + */ class LoggingException: public Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + */ LoggingException(const std::string& source, int line_number, const std::string& method, @@ -57,7 +101,18 @@ public: : Exception(source, line_number, method, code, exception) {}; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + * \param[in] exc Originally raised exception. + */ LoggingException(const std::string& source, int line_number, const std::string& method, @@ -69,10 +124,24 @@ public: }; +/** Exceptions caused by system errors. + * + * This class represents error conditions caused by failing system + * calls. The error message is augmented with the system error message + * obtained by calling strerror(). + */ class OSException: public Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + */ OSException(const std::string& source, int line_number, const std::string& method, @@ -85,7 +154,18 @@ public: exception + ": " + strerror(code)) {}; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param[in] source Source filename where the exception was raised. + * \param[in] line_number Line in the source that caused the exception. + * \param[in] method Name of the method that raised the exception. + * \param[in] code Error code giving the reason for exception. + * \param[in] exception Error message describing the exception. + * \param[in] exc Originally raised exception. + */ OSException(const std::string& source, int line_number, const std::string& method, @@ -101,14 +181,31 @@ public: }; +/** Mandatory exception fields. + * + * This defines the mandatory parameters for all exception + * constructors (filename, line, method name). + */ #define EXCEPTION_MANDATORY \ __FILE__, \ __LINE__, \ std::string(CLASS_PREFIX) + __FUNCTION__ +/** Stacking exceptions. + * + * This was originally used for creating the exception chain; now the + * same result is achieved by adding the nested exception to the + * constructor parameter list. + */ #define STACK_ADD -/* note: we can use __LINE__ several times in macro, it is expanded into one row */ +/** Utility macro to throw LoggingException. + * + * This macro is used to obtain the L&B error message and throw the + * appropriate exception. + * Note: we can use __LINE__ several times in macro, it is expanded into + * one row. + */ #define throw_exception(context, exception) \ { STACK_ADD; \ { \ @@ -134,6 +231,11 @@ public: } \ } +/** Utility macro to check result of L&B calls. + * + * Checks return value of L&B calls and throws exception if the code + * failed. + */ #define check_result(code, context, desc) \ if((code)) throw_exception((context), desc) diff --git a/org.glite.lb.client-interface/interface/Notification.h b/org.glite.lb.client-interface/interface/Notification.h index bc9bf88..6fea744 100644 --- a/org.glite.lb.client-interface/interface/Notification.h +++ b/org.glite.lb.client-interface/interface/Notification.h @@ -25,14 +25,14 @@ public: /** Create from server host,port pair * to be used for new notifications, i.e. with Register() - * \param host IN host - * \param port IN port + * \param[in] host host + * \param[in] port port */ Notification(const std::string host,const u_int16_t port); /** Create from NotifId * to be used for existing notifications, i.e. with Bind() - * \param notifId IN NotifId + * \param[in] notifId NotifId */ Notification(const std::string notifId); @@ -45,12 +45,12 @@ public: /** Add this job to the list. * Local operation only, Register() has to be called * to propagate changes to server - * \param jobId IN JobId + * \param[in] jobId JobId */ void addJob(const glite::wmsutils::jobid::JobId &jobId); /** Remove job from the list, local op again. - * \param jobId IN JobId + * \param[in] jobId JobId */ void removeJob(const glite::wmsutils::jobid::JobId &jobId); @@ -70,7 +70,7 @@ public: /** Bind to the existing notification at the server * i.e. change the receiving local address - * \param address IN address override + * \param[in] address address override */ void Bind(const std::string address); diff --git a/org.glite.lb.client-interface/interface/ServerConnection.h b/org.glite.lb.client-interface/interface/ServerConnection.h index 58a5fc9..43f6607 100644 --- a/org.glite.lb.client-interface/interface/ServerConnection.h +++ b/org.glite.lb.client-interface/interface/ServerConnection.h @@ -19,69 +19,226 @@ EWL_BEGIN_NAMESPACE -/** Auxiliary class to hold an atomic query condition. */ +/** Auxiliary class to hold atomic query condition. + * + * This class is used to construct queries to the L&B database. Each + * query is composed of multiple atomic conditions in the form of + * 'attribute' 'predicate' 'value'. QueryRecord represents such an + * atomic condition. + */ class QueryRecord { public: friend class ServerConnection; friend edg_wll_QueryRec *convertQueryVector(const std::vector &in); /* IMPORTANT: must match lbapi.h */ + /** Symbolic names of queryable attributes. + * + * The queryable attributes correspond to the table columns in + * the bookkeeping server database, they relate both to the + * event records and job records. + * \see Event::Attr + */ enum Attr { UNDEF=0, /**< Not-defined value, used to terminate lists etc. */ - JOBID, /**< Job Id \see _edg_wll_QueryRec */ - OWNER, /**< Job owner \see _edg_wll_QueryRec */ - STATUS, /**< Current job status */ - LOCATION, /**< Where is the job processed */ - DESTINATION, /**< Destination CE */ - DONECODE, /**< Minor done status (OK,fail,cancel) */ - USERTAG, /**< User tag (not implemented yet) */ - TIME, /**< Timestamp \see _edg_wll_QueryRec */ - LEVEL, /**< Logging level (see "dglog.h") * \see _edg_wll_QueryRec */ - HOST, /**< Where the event was generated */ - SOURCE, /**< Source component */ - INSTANCE, /**< Instance of the source component */ - EVENT_TYPE, /**< Event type \see _edg_wll_QueryRec */ - CHKPT_TAG, /**< Checkpoint tag */ + JOBID, /**< Job id. */ + OWNER, /**< Job owner (certificate subject). */ + STATUS, /**< Current job status code. */ + LOCATION, /**< Where is the job being processed. */ + DESTINATION, /**< Destination CE. */ + DONECODE, /**< Minor done status (OK,fail,cancel). */ + USERTAG, /**< User tag. */ + TIME, /**< Timestamp of the event. */ + LEVEL, /**< Logging level. */ + HOST, /**< Hostname where the event was generated. */ + SOURCE, /**< Source component that sent the event. */ + INSTANCE, /**< Instance of the source component. */ + EVENT_TYPE, /**< Event type. */ + CHKPT_TAG, /**< Checkpoint tag. */ RESUBMITTED, /**< Job was resubmitted */ - PARENT, /**< Job was resubmitted */ - EXITCODE, /**< Unix exit code */ + PARENT, /**< Id of the parent job. */ + EXITCODE, /**< Job system exit code. */ }; + /** Symbolic names of predicates. + * + * These are the predicates used for creating atomic query + * conditions. + */ enum Op { - EQUAL=EDG_WLL_QUERY_OP_EQUAL, - LESS=EDG_WLL_QUERY_OP_LESS, - GREATER=EDG_WLL_QUERY_OP_GREATER, - WITHIN=EDG_WLL_QUERY_OP_WITHIN, - UNEQUAL=EDG_WLL_QUERY_OP_UNEQUAL + EQUAL=EDG_WLL_QUERY_OP_EQUAL, /**< Equal. */ + LESS=EDG_WLL_QUERY_OP_LESS, /**< Less than. */ + GREATER=EDG_WLL_QUERY_OP_GREATER, /**< Greater than. */ + WITHIN=EDG_WLL_QUERY_OP_WITHIN, /**< Within the + range. */ + UNEQUAL=EDG_WLL_QUERY_OP_UNEQUAL /**< Not equal. */ }; + + /** Default constructor. + * + * Initializes empty query condition. + */ QueryRecord(); - /* copy and assignment */ - QueryRecord(const QueryRecord &); - QueryRecord& operator=(const QueryRecord &); + /** Copy constructor + * + * Initializes an exact copy of the object. + * \param[in] src Original object. + */ + QueryRecord(const QueryRecord &src); + + /** Assignment operator. + * + * Initializes an exact copy of the object. + * \param[in] src Original object. + * \returns Reference to this object. + */ + QueryRecord& operator=(const QueryRecord &src); + + /** Constructor for condition on string typed value. + * + * Initializes the object to hold condition on string typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const std::string &value); + + /** Constructor for condition on integer typed value. + * + * Initializes the object to hold condition on integer typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const int value); + + /** Constructor for condition on timeval typed value. + * + * Initializes the object to hold condition on timeval typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const struct timeval &value); + + /** Constructor for condition on JobId typed value. + * + * Initializes the object to hold condition on JobId typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const glite::wmsutils::jobid::JobId &value); - /* constructors for simple attribute queries */ - QueryRecord(const Attr, const Op, const std::string &); - QueryRecord(const Attr, const Op, const int); - QueryRecord(const Attr, const Op, const struct timeval &); - QueryRecord(const Attr, const Op, const glite::wmsutils::jobid::JobId&); /* this one is for attr==TIME and particular state */ - QueryRecord(const Attr, const Op, const int, const struct timeval &); + /** Constructor for condition on timeval typed value. + * + * Initializes the object to hold condition on the time the job + * stays in given state. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] state State of thet job. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const int state, const struct timeval &value); /* constructors for WITHIN operator */ - QueryRecord(const Attr, const Op, const std::string &, const std::string &); - QueryRecord(const Attr, const Op, const int, const int); - QueryRecord(const Attr, const Op, const struct timeval &, const struct timeval &); - QueryRecord(const Attr, const Op, const int, const struct timeval &, const struct timeval &); + /** Constructor for condition on string typed interval. + * + * Initializes the object to hold condition on string typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const std::string &value_min, const std::string &value_max); + + /** Constructor for condition on integer typed interval. + * + * Initializes the object to hold condition on integer typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const int value_min, const int value_max); + + /** Constructor for condition on timeval typed interval. + * + * Initializes the object to hold condition on timeval typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const struct timeval &value_min, const struct timeval &value_max); + + /** Constructor for condition on timeval typed interval for + * given state. + * + * Initializes the object to hold condition on the time job + * stayed in given state. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] state State of thet job. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ + QueryRecord(const Attr name, const Op op, const int state, const struct timeval &value_min, const struct timeval &value_max); /* convenience for user tags */ - QueryRecord(const std::string &, const Op, const std::string &); - QueryRecord(const std::string &, const Op, const std::string &, const std::string &); + /** Convenience constructor for condition on user tags. + * + * Initializes the object to hold condition on the value of + * user tag. + * \param[in] tag Name of the tag. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Value of the tag. + */ + QueryRecord(const std::string &tag, const Op op, const std::string &value); + + /** Convenience constructor for condition on user tags. + * + * Initializes the object to hold condition on the value of + * user tag. + * \param[in] tag Name of the tag. + * \param[in] op Symbolic namen of the predicate. + * \param[in] value_min Minimal value of the tag. + * \param[in] value_max Maximal value of the tag. + * \throws Exception Predicate is not WITHIN. + */ + QueryRecord(const std::string &tag, const Op op, const std::string &value_min, const std::string &value_max); + /** Destructor. + * + * The actual work is done by member destructors. + */ ~QueryRecord(); - static const std::string AttrName(const Attr) ; + /** Return the string representation of symbolic attribute + * name. + * \param[in] attr Symbolic attribute name. + * \returns Printable attribute name. + */ + static const std::string AttrName(const Attr attr) ; protected: @@ -103,95 +260,262 @@ private: }; -/** Supported aggregate operations */ +/** Supported aggregate operations. */ enum AggOp { AGG_MIN=1, AGG_MAX, AGG_COUNT }; /** - * Connection to the L&B server. - * Maintain connection to the server. - * Implement non job-specific API calls + * Class representing a connection to the L&B server. + * + * This class serves as an interface for queries not related to + * particular job. The address of the bookkeeping server to query can + * be set arbitrarily during the lifetime of this object, connection + * to the server is maintained automatically by the underlying C API + * layer. This class can be thought of also as an encapsulation of + * edg_wll_Context from L&B C API. + * + * ServerConnection's methods correlate to the L&B C API functions + * taking edg_wll_Context as their first argument and not having + * edg_wll_JobId as the second argument. + * \see edg_wll_Context */ - class ServerConnection { public: + /** \defgroup query Methods for querying the bookkeeping + * server. + * + * These methods serve for obtaining data from the bookkeeping + * server. The L&B service queries come in two flavors: + * \li conjunctive query, as in (cond1) or (cond2) + * \li conjunction of disjunctive queries, as in ( (cond1) + * or (cond2) ) and ( (cond3) or (cond4) ) + * Methods for both query flavors are provided. + * + * Query methods actually do communicate with the server and + * they are synchronous; their completion can take some time + * not exceeding the query timeout. + */ + + /** \defgroup property Methods for setting and getting + * connection properties. + * + * These methods are used for setting and obtaining various + * parameters of the communication (timeouts, user + * certificates, limits). Both general methods (taking the + * symbolic name of the parameter as an argument) and + * convenience methods (for some parameters) are provided. + * + * The methods are local, no communication takes place. + */ + friend class Job; + /** Default constructor. + * + * Initializes the context to default values. + * \throws OSException Initialization failed. + */ ServerConnection(void); - /* DEPRECATED: do not use - * connections are now handled automagically inside the implementation + /** DEPRECATED. + * + * \throws Exception Always. */ ServerConnection(const std::string &); - /** Open connection to a given server */ + /** DEPRECATED. + * + * \throws Exception Always. + */ void open(const std::string &); - /** Close the current connection */ + /** DEPRECATED. + * + * \throws Exception Always. + */ void close(void); /* END DEPRECATED */ /* set & get parameter methods */ - /* consumer parameter settings */ - void setQueryServer(const std::string&, int); - void setQueryTimeout(int); - - void setX509Proxy(const std::string&); - void setX509Cert(const std::string&, const std::string&); - + /** Set bookkeeping server address. + * \ingroup property + * + * Directs the instance to query the given bookkeping server. + * \param[in] host Hostname of the server. + * \param[in] port Service port. + * \throws LoggingException Setting parameters failed. + */ + void setQueryServer(const std::string& host, int port); + + /** Set query timeout. + * \ingroup property + * + * Sets the time interval to wait for server response. + * \param[in] time Time in seconds before the query expires. + * \throws LoggingException Setting parameters failed. + */ + void setQueryTimeout(int time); + + /** Set user's proxy certificate. + * \ingroup property + * + * Instructs the instance to authenticate to the server using + * user's X509 proxy certificate. + * \param[in] proxy Name of file containing the user's proxy certificate. + * \throws LoggingException Setting paramater failed. + */ + void setX509Proxy(const std::string& proxy); + + /** Set user's certificate. + * \ingroup property + * + * Instructs the instance to authenticate to the server using + * users's full X509 certificate (which is not a good thing). + * \param[in] cert Name of file containing the user's certificate. + * \param[in] key Name of file containing the user's private + * key. + * \throws LoggingException Setting parameters failed. + */ + void setX509Cert(const std::string& cert, const std::string& key); + + /** Get address of the bookkeeping server. + * \ingroup property + * + * Returns address of the bookkeeping server this instance is + * bound to. + * \returns Address (hostname,port). + * \throws LoggingException Getting parameter failed. + */ std::pair getQueryServer() const; + + /** Get query timeout. + * \ingroup property + * + * Returns the time interval this instance waits for server + * response. + * \returns Number of seconds to wait. + * \throws LoggingException Getting parameter failed. + */ int getQueryTimeout() const; + /** Get user's proxy. + * \ingroup property + * + * Returns filename of the user's X509 proxy certificate used + * to authenticate to the server. + * \returns Filename of the proxy certificate. + * \throws LoggingException Getting parameter failed. + */ std::string getX509Proxy() const; + + /** Get user's X509 certificate. + * \ingroup property + * + * Returns filenames of the user's full X509 certificate used + * to authenticate to the server. + * \returns Pair of (certificate, key) filenames. + * \throws LoggingException Getting parameter failed. + */ std::pair getX509Cert() const; /* end of set & get */ + /** Destructor. + * + * Closes the connections and frees the context. + */ virtual ~ServerConnection(); /* consumer API */ /** Retrieve the set of single indexed attributes. - * outer vector elements correspond to indices - * inner vector elements correspond to index columns - * if .first of the pair is USERTAG, .second is its name - * if .first is TIME, .second is state name - * otherwise .second is meaningless (empty string anyway) + * \ingroup query + * + * Returns the set of attributes that are indexed on the + * server. Every query must contain at least one indexed + * attribute for performance reason; exception to this rule + * requires setting appropriate paramater on the server and is + * not advised. + * + * In the vector returned, outer elements correspond to indices, + * inner vector elements correspond to index + * columns. + * If .first of the pair is USERTAG, .second is its name; + * if .first is TIME, .second is state name + * otherwise .second is meaningless (empty string anyway). */ std::vector > > getIndexedAttrs(void); - /** Retrieve hard and soft result set size limit */ - std::pair getLimits(void) const; - - /** Set the soft result set size limit */ - void setQueryJobsLimit(int); - void setQueryEventsLimit(int); + /* Retrieve hard and soft result set size limit. + * \ingroup property + * + * Returns both the hard and soft limit on the number of + * results returned by the bookkeeping server. + * \returns Pair (hard, soft) of limits. + * \throws + */ + // std::pair getLimits(void) const; + + /** Set the soft result set size limit. + * \ingroup property + * + * Sets the maximum number of results this instance is willing + * to obtain when querying for jobs. + * \param max Maximum number of results. + * \throws LoggingException Setting parameter failed. + */ + void setQueryJobsLimit(int max); + + /** Set the soft result set size limit. + * \ingroup property + * + * Sets the maximum number of results this instance is willing + * to obtain when querying for Events. + * \param max Maximum number of results. + * \throws LoggingException Setting parameter failed. + */ + void setQueryEventsLimit(int max); - /** Retrieve all events satisfying the query records - * @param job_cond, event_cond - vectors of conditions to be satisfied - * by jobs as a whole or particular events, conditions are ANDed - * @param events vector of returned events + /** Retrieve all events satisfying the query records. + * \ingroup query + * + * Returns all events belonging to the jobs specified by \arg + * job_cond and in addition satisfying the \arg event_cond. + * \param[in] job_cond Conjunctive query on jobs. + * \param[in] event_cond Conjunctive query on events. + * \param[out] events Vector of Event objects representing L&B + * events. + * \throws LoggingException Query failed. */ void queryEvents(const std::vector& job_cond, const std::vector& event_cond, std::vector& events) const; + /** Convenience form of queryEvents. + * + */ const std::vector queryEvents(const std::vector& job_cond, const std::vector& event_cond) const; + /** Another modification of queryEvents. + * + * The same method, but the results are returned as a list + * instead of vector. + */ const std::list queryEventsList(const std::vector& job_cond, const std::vector& event_cond) const; - /** The same as queryEvents but return only an aggregate. - * @param job_cond, event_cond - vectors of conditions to be satisfied - * by jobs as a whole or particular events, conditions are ANDed - * @param op aggregate operator to apply - * @param attr attribute to apply the operation to + /** NOT IMPLEMENTED. + * \param[in] job_cond + * \param[in] event_cond Vectors of conditions to be satisfied + * by jobs as a whole or particular events. + * \param[in] op Aggregate operator to apply. + * \param[in] attr Attribute to apply the operation to. */ std::string queryEventsAggregate(const std::vector& job_cond, const std::vector& event_cond, @@ -199,91 +523,204 @@ public: std::string const attr) const; - /** Retrieve all events satisfying the query records - * @param job_cond, event_cond IN vectors of vectors of job or event conditions, - * respectively. The inner vectors are logically ANDed, the outer are ORed - * (cond1 AND cond2 AND ...) OR (condN AND ...) - * @param eventList OUT vector of returned events + /** Retrieve all events satisfying the conjunctive-disjunctive + * query. + * + * Returns all events belonging to the jobs specified by + * job_cond and satisfying query_cond. The + * conditions are given in conjunctive-disjunctive form + * ((cond1 OR cond2 OR ...) AND ...) + * \param[in] job_cond Vector of conditions on jobs. + * \param[in] event_cond Vector of coditions on events. + * \param[out] eventList Returned Event's. + * \throws LoggingException Query failed. */ void queryEvents(const std::vector >& job_cond, const std::vector >& event_cond, std::vector& eventList) const; + /** Convenience form of queryEvents. + * + * The same as previous, but the resulting vector is passed as + * a return value. + */ const std::vector queryEvents(const std::vector >& job_cond, const std::vector >& event_cond) const; - /** Retrieve jobs satisfying the query records, including their states - * @param query IN vector of Query records that are ANDed to form the query - * @param jobList OUT vector of returned job id's + /** Retrieve jobs satisfying the query. + * + * Finds all jobs (represented as JobId's) satisfying given + * query. + * \param[in] query Query in conjunctive form. + * \param[out] jobList List of job id's. + * \throws LoggingException Query failed. */ - void queryJobs(const std::vector& query, std::vector& jobList) const; - + + /** Convenience form of queryJobs. + * + * The same as above, but job id's are passed as a return + * value. + */ const std::vector queryJobs(const std::vector& query) const; - /** Retrieve jobs satisfying the query records, including their states - * @param query IN vector of Query record vectors that are ORed and ANDed to form the query - * @param jobList OUT vector of returned job id's + /** Retrieve jobs satisfying the query. + * + * Finds all jobs satisfying query given in + * conjunctive-disjunctive form. + * \param[in] query Conjunction of disjunctive queries. + * \param[out] jobList Job id's of found jobs. + * \throws LoggingException Query failed. */ - void queryJobs(const std::vector >& query, std::vector& jobList) const; + /** Convenience form of queryJobs. + * + * Same as above, but result is passed as a retutrn value. + */ const std::vector queryJobs(const std::vector >& query) const; - /** Retrieve jobs satisfying the query records, including status information - * @param query IN vector of Query records that are ANDed to form the query - * @param flags IN flags - * @param states OUT vector of returned job states + /** Retrieve status of jobs satisfying the given simple query. + * + * Returns states (represented by JobStatus) of all jobs + * satisfying the query in conjunctive form. + * \param[in] query Condition on jobs. + * \param[in] flags The same as Job::status() flags. + * \param[out] states States of jobs satysfying the condition. + * \throws LoggingException Query failed. */ void queryJobStates(const std::vector& query, int flags, std::vector & states) const; + + /** Convenience form of queryJobStates. + * + * Same as above, but the result is passed as a return value. + */ const std::vector queryJobStates(const std::vector& query, int flags) const; + /** Convenience form of queryJobStates. + * + * Same as above, but results are returned as list instead of + * vector. + */ const std::list queryJobStatesList(const std::vector& query, int flags) const; - /** Retrieve jobs satisfying the query records, including status information - * @param query IN vector of Query records that are anded to form the query - * @param flags IN flags - * @param states OUT vector of returned job states + /** Retrieve status of jobs satisfying the given + * conjunctive-disjunctive query. + * + * Returns states (represented by JobStatus) of all jobs + * satisfying the query in conjunctive form. + * \param[in] query Condition on jobs. + * \param[in] flags The same as Job::status() flags. + * \param[out] states States of jobs satysfying the condition. + * \throws LoggingException Query failed. */ void queryJobStates(const std::vector >& query, int flags, std::vector & states) const; + + /** Convenience form of queryJobStates. + * + * Same as above, but the result is passed as a return value. + */ const std::vector queryJobStates(const std::vector >& query, int flags) const; - /** States of all user's jobs. - * Convenience wrapper around queryJobs. + /** Return states of all user's jobs. + * + * Convenience wrapper around queryJobStates, returns status of all + * jobs whose owner is the current user (as named in the X509 + * certificate subject). + * \param[out] stateList States of jobs owned by this user. + * \throws LoggingException Query failed. */ void userJobStates(std::vector& stateList) const; const std::vector userJobStates() const; - /** JobId's of all user's jobs. - * Convenience wrapper around queryJobs. + /** Find all user's jobs. + * + * Convenience wrapper around queryJobs, returns id's of all + * jobs whose owner is the current user (as named in the X509 + * certificate subject). + * \param[out] jobs Id's of jobs owned by this user. + * \throws LoggingException Query failed. */ - void userJobs(std::vector &) const; - const std::vector userJobs() const; + void userJobs(std::vector &jobs) const; - /** Manipulate LB parameters, the same as for edg_wll_Context in C */ - void setParam(edg_wll_ContextParam, int); - void setParam(edg_wll_ContextParam, const std::string); - void setParam(edg_wll_ContextParam, const struct timeval &); + /** Convenience form of userJobs. + * + * Same as above, but results are passed as a return value. + */ + const std::vector userJobs() const; - int getParamInt(edg_wll_ContextParam) const; - std::string getParamString(edg_wll_ContextParam) const; - struct timeval getParamTime(edg_wll_ContextParam) const; + /** Set communication parameters of integer type. + * + * Sets the named parameter to the given integer value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, int value); + + /** Set communication parameters of string type. + * + * Sets the named parameter to the given string value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, const std::string &value); + + /** Set communication parameters of timeval type. + * + * Sets the named parameter to the given timeval value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, const struct timeval &value); + + /** Get communication parameters of integer type. + * + * Gets the named parameter of integer type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + int getParamInt(edg_wll_ContextParam name) const; + + /** Get communication parameters of string type. + * + * Gets the named parameter of string type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + std::string getParamString(edg_wll_ContextParam name) const; + + /** Get communication parameters of timeval type. + * + * Gets the named parameter of timeval type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + struct timeval getParamTime(edg_wll_ContextParam name) const; protected: diff --git a/org.glite.lb.client-interface/interface/consumer.h b/org.glite.lb.client-interface/interface/consumer.h index d34c6de..ed2084d 100644 --- a/org.glite.lb.client-interface/interface/consumer.h +++ b/org.glite.lb.client-interface/interface/consumer.h @@ -4,15 +4,6 @@ /*! * \file consumer.h * \brief L&B consumer API - * - * General rules: - * - functions return 0 on success, nonzero on error, errror details can - * be found via edg_wll_ErrorCode() - * - OUT are ** types, functions malloc()-ate objects and fill in the pointer - * pointed to by the OUT argument - * - returned lists of pointers are NULL-terminated malloc()-ed arrays - * - edg_wll_Query + wrapper terminate arrays with EDG_WLL_EVENT_UNDEF event - * - OUT is NULL if the list is empty */ #ident "$Header$" @@ -26,7 +17,27 @@ extern "C" { #endif -/*! +/** + * \defgroup querying Server querying + * \brief The core part of the LB querying API. + * + * The functions in this part of the API are responsible for + * transforming the user query to the LB protocol, contacting the server, + * receiving back the response and transforming back the results to the + * API data structures. + * + * General rules: + * - functions return 0 on success, nonzero on error, errror details can + * be found via edg_wll_ErrorCode() + * - OUT are ** types, functions malloc()-ate objects and fill in the pointer + * pointed to by the OUT argument + * - returned lists of pointers are NULL-terminated malloc()-ed arrays + * - edg_wll_Query + wrapper terminate arrays with EDG_WLL_EVENT_UNDEF event + * - OUT is NULL if the list is empty + *@{ + */ + +/** * Predefined types for query attributes */ typedef enum _edg_wll_QueryAttr{ @@ -53,7 +64,7 @@ typedef enum _edg_wll_QueryAttr{ } edg_wll_QueryAttr; -/*! +/** * Predefined types for query operands */ typedef enum _edg_wll_QueryOp{ @@ -65,7 +76,7 @@ typedef enum _edg_wll_QueryOp{ } edg_wll_QueryOp; -/*! +/** * Single query condition for edg_wll_Query(). * Those records are composed to form an SQL \a where clause * when processed at the L&B server @@ -93,36 +104,15 @@ typedef struct _edg_wll_QueryRec { } value, value2; } edg_wll_QueryRec; -/************************************************ - * API FUNCTION DECLARATIONS * +/** + * default query timeout (in seconds) */ - - -#ifdef CLIENT_SBIN_PROG -extern int edg_wll_http_send_recv( - edg_wll_Context, - char *, const char * const *, char *, - char **,char ***,char ** -); - -extern int http_check_status( - edg_wll_Context, - char *, - char ** -); - -extern int set_server_name_and_port( - edg_wll_Context, - const edg_wll_QueryRec ** -); - -#endif +#define EDG_WLL_QUERY_TIMEOUT_DEFAULT 120 /** - * \name Server querying - * - *@{ + * maximal query timeout (in seconds) */ +#define EDG_WLL_QUERY_TIMEOUT_MAX 1800 /** * General query on events. @@ -131,10 +121,10 @@ extern int set_server_name_and_port( * \a attr \a op \a value eg. time > 87654321. * \see edg_wll_QueryRec * - * \param context IN: context to work with - * \param job_conditions IN: query conditions (ANDed) on current job status, null (i.e. ATTR_UNDEF) terminated list. NULL means empty list, i.e. always TRUE - * \param event_conditions: IN: conditions on events, null terminated list, NULL means empty list, i.e. always TRUE - * \param events OUT: list of matching events + * \param[in] context context to work with + * \param[in] job_conditions query conditions (ANDed) on current job status, null (i.e. ATTR_UNDEF) terminated list. NULL means empty list, i.e. always TRUE + * \param[in] event_conditions conditions on events, null terminated list, NULL means empty list, i.e. always TRUE + * \param[out] events list of matching events */ int edg_wll_QueryEvents( edg_wll_Context context, @@ -143,6 +133,14 @@ int edg_wll_QueryEvents( edg_wll_Event ** events ); +/** + * Extended event query interface. + * Similar to \ref edg_wll_QueryEvents but the conditions are nested lists. + * Elements of the inner lists have to refer to the same attribute and they + * are logically ORed. + * The inner lists themselves are logically ANDed then. + */ + int edg_wll_QueryEventsExt( edg_wll_Context context, const edg_wll_QueryRec ** job_conditions, @@ -153,6 +151,7 @@ int edg_wll_QueryEventsExt( /** * Query LBProxy and use plain communication + * \warning edg_wll_*Proxy() functions are not implemented in release 1. */ int edg_wll_QueryEventsProxy( edg_wll_Context context, @@ -161,6 +160,10 @@ int edg_wll_QueryEventsProxy( edg_wll_Event ** events ); +/** + * \warning edg_wll_*Proxy() functions are not implemented in release 1. + */ + int edg_wll_QueryEventsExtProxy( edg_wll_Context context, const edg_wll_QueryRec ** job_conditions, @@ -173,11 +176,11 @@ int edg_wll_QueryEventsExtProxy( * Return jobs (and possibly their states) for which an event satisfying the conditions * exists. * \see edg_wll_QueryEvents - * \param context IN: context to work with - * \param conditions IN: query records (ANDed), null (i.e. EDG_WLL_ATTR_UNDEF) terminated list - * \param flags IN: additional status fields to retrieve (\see edg_wll_JobStatus) - * \param jobs OUT: list of job ids. May be NULL. - * \param states OUT: list of corresponding states (returned only if not NULL) + * \param[in] context context to work with + * \param[in] conditions query records (ANDed), null (i.e. EDG_WLL_ATTR_UNDEF) terminated list + * \param[in] flags additional status fields to retrieve (\see edg_wll_JobStatus) + * \param[out] jobs list of job ids. May be NULL. + * \param[out] states list of corresponding states (returned only if not NULL) */ int edg_wll_QueryJobs( edg_wll_Context context, @@ -187,6 +190,15 @@ int edg_wll_QueryJobs( edg_wll_JobStat ** states ); +/** + * Extended job query interface. + * Similar to \ref edg_wll_QueryJobs but the conditions are nested lists. + * Elements of the inner lists have to refer to the same attribute and they + * are logically ORed. + * The inner lists themselves are logically ANDed then. + */ + + int edg_wll_QueryJobsExt( edg_wll_Context context, const edg_wll_QueryRec ** conditions, @@ -198,6 +210,7 @@ int edg_wll_QueryJobsExt( /** * Query LBProxy and use plain communication + * \warning edg_wll_*Proxy() functions are not implemented in release 1. */ int edg_wll_QueryJobsProxy( edg_wll_Context context, @@ -207,6 +220,10 @@ int edg_wll_QueryJobsProxy( edg_wll_JobStat ** states ); +/** + * \warning edg_wll_*Proxy() functions are not implemented in release 1. + */ + int edg_wll_QueryJobsExtProxy( edg_wll_Context context, const edg_wll_QueryRec ** conditions, @@ -227,11 +244,11 @@ int edg_wll_QueryJobsExtProxy( /* starting from bit 10 private flags begins - do not add 1024 and more! */ /** Return status of a single job. - * \param context IN: context to operate on - * \param jobid IN: query this job - * \param flags IN: specifies optional status fields to retrieve, + * \param[in] context context to operate on + * \param[in] jobid query this job + * \param[in] flags specifies optional status fields to retrieve, * \see EDG_WLL_STAT_CLASSADS, EDG_WLL_STAT_CHILDREN, EDG_WLL_STAT_CHILDSTAT - * \param status OUT: status + * \param[out] status status */ int edg_wll_JobStatus( @@ -243,11 +260,13 @@ int edg_wll_JobStatus( /** * Query LBProxy and use plain communication - * \param context IN: context to operate on - * \param jobid IN: query this job - * \param flags IN: specifies optional status fields to retrieve, + * \param[in] context context to operate on + * \param[in] jobid query this job + * \param[in] flags specifies optional status fields to retrieve, * \see EDG_WLL_STAT_CLASSADS, EDG_WLL_STAT_CHILDREN, EDG_WLL_STAT_CHILDSTAT - * \param status OUT: the status of the job + * \param[out] status the status of the job + + * \warning edg_wll_*Proxy() functions are not implemented in release 1. */ int edg_wll_JobStatusProxy( edg_wll_Context context, @@ -259,9 +278,9 @@ int edg_wll_JobStatusProxy( /** * Return all events related to a single job. * Convenience wrapper around edg_wll_Query() - * \param context IN: context to work with - * \param jobId IN: job to query - * \param events OUT: list of events + * \param[in] context context to work with + * \param[in] jobId job to query + * \param[out] events list of events */ int edg_wll_JobLog( @@ -273,6 +292,8 @@ int edg_wll_JobLog( /** * Query LBProxy and use plain communication + * \warning edg_wll_*Proxy() functions are not implemented in release 1. + */ int edg_wll_JobLogProxy( edg_wll_Context context, @@ -282,9 +303,9 @@ int edg_wll_JobLogProxy( /** * All current user's jobs. - * \param context IN: context to work with - * \param jobs OUT: list of the user's jobs - * \param states OUT: list of the jobs' states + * \param[in] context context to work with + * \param[out] jobs list of the user's jobs + * \param[out] states list of the jobs' states */ int edg_wll_UserJobs( edg_wll_Context context, @@ -295,6 +316,8 @@ int edg_wll_UserJobs( /** * Query LBProxy and use plain communication + * \warning edg_wll_*Proxy() functions are not implemented in release 1. + */ int edg_wll_UserJobsProxy( edg_wll_Context context, @@ -305,8 +328,8 @@ int edg_wll_UserJobsProxy( /** * Server supported indexed attributes * \see DataGrid-01-TEN-0125 - * \param context IN: context to work with - * \param attrs OUT: configured indices (each index is an UNDEF-terminated + * \param[in] context context to work with + * \param[out] attrs configured indices (each index is an UNDEF-terminated * array of QueryRec's from which only attr (and attr_id * eventually) are meaningful */ @@ -317,10 +340,10 @@ int edg_wll_GetIndexedAttrs( /** * Retrieve limit on query result size (no. of events or jobs). - * FIXME: not implemented. + * \warning not implemented. * \see DataGrid-01-TEN-0125 - * \param context IN: context to work with - * \param limit OUT: server imposed limit + * \param[in] context context to work with + * \param[out] limit server imposed limit */ int edg_wll_GetServerLimit( edg_wll_Context context, @@ -328,12 +351,12 @@ int edg_wll_GetServerLimit( ); /** - * UI port for the job - * \param context IN: context to work with - * \param jobId IN: job to query - * \param name IN: name of the UI-port - * \param host OUT: hostname of port - * \param port OUT: port number + * UI port for intactive jobs. Used internally by WMS. + * \param[in] context context to work with + * \param[in] jobId job to query + * \param[in] name name of the UI-port + * \param[out] host hostname of port + * \param[out] port port number */ int edg_wll_QueryListener( edg_wll_Context context, @@ -357,9 +380,9 @@ int edg_wll_QueryListenerProxy( /** * Ask LB Proxy server for sequence number - * \param context IN: context to work with - * \param jobId IN: job to query - * \param code OUT: sequence code + * \param[in] context context to work with + * \param[in] jobId job to query + * \param[out] code sequence code */ @@ -369,8 +392,6 @@ int edg_wll_QuerySequenceCodeProxy( char ** code ); -/*@}*/ - /* * edg_wll_QueryRec manipulation */ @@ -378,7 +399,29 @@ int edg_wll_QuerySequenceCodeProxy( /** Free edg_wll_QueryRec internals, not the structure itself */ void edg_wll_QueryRecFree(edg_wll_QueryRec *); +/* + *@} end of group + */ + +#ifdef CLIENT_SBIN_PROG +extern int edg_wll_http_send_recv( + edg_wll_Context, + char *, const char * const *, char *, + char **,char ***,char ** +); +extern int http_check_status( + edg_wll_Context, + char *, + char ** +); + +extern int set_server_name_and_port( + edg_wll_Context, + const edg_wll_QueryRec ** +); + +#endif /** * default query timeout (in seconds) diff --git a/org.glite.lb.client-interface/interface/context.h b/org.glite.lb.client-interface/interface/context.h index 1ff707f..b1e366a 100644 --- a/org.glite.lb.client-interface/interface/context.h +++ b/org.glite.lb.client-interface/interface/context.h @@ -15,6 +15,12 @@ extern "C" { #endif +/** + * \defgroup context Context + * + *@{ + */ + /** Opaque context type */ typedef struct _edg_wll_Context *edg_wll_Context; @@ -78,21 +84,21 @@ typedef enum _edg_wll_Source { /** Allocate an initialize a new context object. - * \param context OUT returned context + * \param[out] context returned context * \return 0 on success, ENOMEM if malloc() fails */ int edg_wll_InitContext(edg_wll_Context *context); /** Destroy and free context object. * Also performs necessary cleanup (closing connections etc.) - * \param context IN context to free + * \param[in] context context to free */ void edg_wll_FreeContext(edg_wll_Context context); /** Set a context parameter. - * \param context INOUT context to work with - * \param param IN parameter to set - * \param ... IN value to set (if NULL or 0, default is used) + * \param[in,out] context context to work with + * \param[in] param parameter to set + * \param[in] ... value to set (if NULL or 0, default is used) * \retval 0 success * \retval EINVAL param is not a valid parameter, or invalid value */ @@ -102,39 +108,39 @@ int edg_wll_SetParam( ... ); -struct timeval; /* XXX: gcc, shut up! */ +struct timeval; /* XXX: gcc, shut up! */ /** Set a context parameter of type int. - * \param ctx INOUT context to work with - * \param param IN parameter to set - * \param val IN value to set - * \retval 0 success - * \retval EINVAL param is not a valid parameter, or invalid value + * \param[in,out] ctx context to work with + * \param[in] param parameter to set + * \param[in] val value to set + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value */ int edg_wll_SetParamInt(edg_wll_Context ctx,edg_wll_ContextParam param,int val); /** Set a context parameter of type string. - * \param ctx INOUT context to work with - * \param param IN parameter to set - * \param val In value to set (if NULL, default is used) - * \retval 0 success - * \retval EINVAL param is not a valid parameter, or invalid value + * \param[in,out] ctx context to work with + * \param[in] param parameter to set + * \param[in] val value to set (if NULL, default is used) + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value */ int edg_wll_SetParamString(edg_wll_Context ctx,edg_wll_ContextParam param,const char *val); /** Set a context parameter of type timeval. - * \param ctx INOUT context to work with - * \param param IN parameter to set - * \param val IN value to set (if NULL, default is used) - * \retval 0 success - * \retval EINVAL param is not a valid parameter, or invalid value + * \param[in,out] ctx context to work with + * \param[in] param parameter to set + * \param[in] val value to set (if NULL, default is used) + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value */ int edg_wll_SetParamTime(edg_wll_Context ctx,edg_wll_ContextParam param,const struct timeval *val); /** Get current parameter value. - * \param context INOUT context to work with - * \param param IN parameter to retrieve - * \param ... OUT pointer to output variable + * \param[in,out] context context to work with + * \param[in] param parameter to retrieve + * \param[out] ... pointer to output variable * \retval 0 success * \retval EINVAL param is not a valid parameter */ @@ -183,10 +189,10 @@ typedef enum _edg_wll_ErrorCode { /** * Retrieve error details on recent API call - * \param context IN: context to work with - * \param errText OUT: standard error text + * \param[in] context context to work with + * \param[out] errText standard error text * (may be NULL - no text returned) - * \param errDesc OUT: additional error description + * \param[out] errDesc additional error description * (may be NULL - no text returned) * \return Error code of the recent error */ @@ -239,6 +245,10 @@ int edg_wll_GetLoggingJob( edg_wlc_JobId *jobid_out ); +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/events.h.T b/org.glite.lb.client-interface/interface/events.h.T index e9be675..ddb1674 100644 --- a/org.glite.lb.client-interface/interface/events.h.T +++ b/org.glite.lb.client-interface/interface/events.h.T @@ -22,6 +22,12 @@ extern "C" { #endif +/** + * \defgroup events Events + * \brief All L&B event types. + * + *@{ + */ /** * Predefined type for ULM string @@ -48,22 +54,22 @@ for my $e (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } } edg_wll_EventCode; /** - * \fn edg_wll_EventCode edg_wll_StringToEvent(char *name) - * \param name a string event name (e.g. "JobTransfer") + * \fn edg_wll_EventCode edg_wll_StringToEvent(const char *name) + * \param[in] name a string event name (e.g. "JobTransfer") * \return corresponding numeric code (edg_wll_EventCode) * \brief convert a string event name to the corresponding numeric code */ -extern edg_wll_EventCode edg_wll_StringToEvent(char *); +extern edg_wll_EventCode edg_wll_StringToEvent(const char *name); /** * \fn char *edg_wll_EventToString(edg_wll_EventCode event) - * \param event an event numeric code (edg_wll_EventCode) + * \param[in] event an event numeric code (edg_wll_EventCode) * \return corresponding string (e.g. "JobTransfer") * \brief convert an event numeric code to the corresponding string */ -extern char *edg_wll_EventToString(edg_wll_EventCode); +extern char *edg_wll_EventToString(edg_wll_EventCode event); /** @@ -102,22 +108,22 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } } edg_wll_KeyNameCode; /** - * \fn edg_wll_KeyNameCode edg_wll_StringToKeyName(char *name) - * \param name a string ULM key name (e.g. "DG.JOB.TRANSFER.DEST") + * \fn edg_wll_KeyNameCode edg_wll_StringToKeyName(const char *name) + * \param[in] name a string ULM key name (e.g. "DG.JOB.TRANSFER.DEST") * \return corresponding numeric code (edg_wll_KeyNameCode) * \brief convert a string ULM key name to the corresponding numeric code */ -extern edg_wll_KeyNameCode edg_wll_StringToKeyName(char *); +extern edg_wll_KeyNameCode edg_wll_StringToKeyName(const char *name); /** * \fn char *edg_wll_KeyNameToString(edg_wll_KeyNameCode key) - * \param key a ULM key name numeric code (edg_wll_KeyNameCode) + * \param[in] key a ULM key name numeric code (edg_wll_KeyNameCode) * \return corresponding string (e.g. "DG.JOB.TRANSFER.DEST") * \brief convert a ULM key name numeric code to the corresponding string */ -extern char *edg_wll_KeyNameToString(edg_wll_KeyNameCode); +extern char *edg_wll_KeyNameToString(edg_wll_KeyNameCode key); /** @@ -152,19 +158,19 @@ $enum \{ # function StringTo: gen qq{ /** - * \\fn $enum edg_wll_StringTo${c}(char *name); - * \\param name a string representing $fn code (e.g. \"${$f->{codes}}[1]->{name}\") + * \\fn $enum edg_wll_StringTo${c}(const char *name); + * \\param[in] name a string representing $fn code (e.g. \"${$f->{codes}}[1]->{name}\") * \\return corresponding numeric code ($enum) * \\brief converts a string $fn code to corresponding numeric code */ -extern $enum edg_wll_StringTo${c}(char *name); +extern $enum edg_wll_StringTo${c}(const char *name); }; # function ToString: gen qq{ /** * \\fn char *edg_wll\_${c}ToString($enum code); - * \\param code a $fn numeric code ($enum) + * \\param[in] code a $fn numeric code ($enum) * \\return corresponding string (e.g. \"${$f->{codes}}[1]->{name}\") * \\brief converts a $fn numeric code to corresponding string */ @@ -200,19 +206,19 @@ $enum \{ # function StringTo: gen qq{ /** - * \\fn $enum edg_wll_StringTo${c}(char *name); - * \\param name a string representing $t $fn code (e.g. \"${$f->{codes}}[1]->{name}\") + * \\fn $enum edg_wll_StringTo${c}(const char *name); + * \\param[in] name a string representing $t $fn code (e.g. \"${$f->{codes}}[1]->{name}\") * \\return corresponding numeric code ($enum) * \\brief converts a string $t $fn code to corresponding numeric code */ -extern $enum edg_wll_StringTo${c}(char *name); +extern $enum edg_wll_StringTo${c}(const char *name); }; # function ToString: gen qq{ /** * \\fn char *edg_wll\_${c}ToString($enum code); - * \\param code a $t $fn numeric code ($enum) + * \\param[in] code a $t $fn numeric code ($enum) * \\return corresponding string (e.g. \"${$f->{codes}}[1]->{name}\") * \\brief converts a $t $fn numeric code to corresponding string */ @@ -317,7 +323,7 @@ extern edg_wll_Event *edg_wll_InitEvent(edg_wll_EventCode eventcode); /** * Free the contents of event structure - * \param event IN structure to be freed + * \param[in] event structure to be freed * \warning As event structures are likely to be allocated in arrays, * the structure itself is not freed. * Its the responsibility of the caller to call free(event) @@ -327,6 +333,9 @@ void edg_wll_FreeEvent( edg_wll_Event * event ); +/* + *@} end of group + */ #ifdef __cplusplus } diff --git a/org.glite.lb.client-interface/interface/jobstat.h.T b/org.glite.lb.client-interface/interface/jobstat.h.T index 802f119..4647f1a 100644 --- a/org.glite.lb.client-interface/interface/jobstat.h.T +++ b/org.glite.lb.client-interface/interface/jobstat.h.T @@ -17,6 +17,12 @@ extern "C" { #endif /** + * \defgroup jobstatus Job Status + * \brief Job status structure definition and related definitions. + *@{ + */ + +/** * Miscelaneous job status numeric codes */ @@ -101,8 +107,6 @@ typedef struct _edg_wll_JobStat { * \name edg_wll_JobStat manipulation */ -/*@{*/ - /** * Initialize empty status structure. * Fills in the stucture with NULL's or values with no meaning @@ -134,6 +138,10 @@ extern char *edg_wll_StatToString(edg_wll_JobStatCode); /*@}*/ +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/notification.h b/org.glite.lb.client-interface/interface/notification.h index 5c87c0f..0a92c60 100644 --- a/org.glite.lb.client-interface/interface/notification.h +++ b/org.glite.lb.client-interface/interface/notification.h @@ -13,6 +13,12 @@ extern "C" { #endif /** + * \defgroup notifications Notifications handling + * \brief Notifications handling. + *@{ + */ + +/** * default and maximal notif timeout (in seconds) */ #define EDG_WLL_NOTIF_TIMEOUT_DEFAULT 120 @@ -22,17 +28,19 @@ extern "C" { /** Register for receiving notifications. * Connects to the server specified by EDG_WLL_NOTIF_SERVER context parameter * (temporary workaround, should be resolved by registry in future). - * \param conditions: the same conditions as for \see edg_wll_QueryJobsExt. + * \param[in,out] context context to work with + * \param[in] conditions the same conditions as for \ref edg_wll_QueryJobsExt. * currently one or more JOBID's are required. * Only a single occurence of a specific attribute is allowed * among ANDed conditions (due to the ability to modify them * further). - * \param fd = -1 create or reuse the default listening socket (one per context) + * \param[in] fd = -1 create or reuse the default listening socket (one per context) * >= 0 non-default listening socket - * \param address_override if not NULL, use this address instead of extracting it + * \param[in] address_override if not NULL, use this address instead of extracting it * from the connection (useful when multiple interfaces are present, * circumventing NAT problems etc.) - * \param valid until when the registration is valid (NULL means no interest in + * \param[in] valid until when the registration is valid (NULL means no interest in + * \param[out] id_out returened NotifId * the value * \retval 0 OK * \retval EINVAL restrictions on conditions are not met @@ -51,9 +59,11 @@ int edg_wll_NotifNew( /** Change the receiving local address. * Report the new address to the server. * - * \param fd - * \param address_override - * \param valid all same as for \see edg_wll_NotifNew + * \param[in,out] context context to work with + * \param[in] id notification ID you are binding to + * \param[in] fd same as for \ref edg_wll_NotifNew + * \param[in] address_override same as for \ref edg_wll_NotifNew + * \param[in] valid same as for \ref edg_wll_NotifNew */ int edg_wll_NotifBind( @@ -65,9 +75,13 @@ int edg_wll_NotifBind( ); typedef enum _edg_wll_NotifChangeOp { + /** No operation, equal to not defined */ EDG_WLL_NOTIF_NOOP = 0, + /** Replace notification registration with new one */ EDG_WLL_NOTIF_REPLACE, + /** Add new condition when to be notifed */ EDG_WLL_NOTIF_ADD, + /** Remove condition on notification */ EDG_WLL_NOTIF_REMOVE /* if adding new attribute, add conversion string to common/xml_conversions.c too !! */ } edg_wll_NotifChangeOp; @@ -78,8 +92,11 @@ typedef enum _edg_wll_NotifChangeOp { * of uniqueness the original conditions must have contained only a single * OR-ed row of conditions on the attributes infolved in the change. * - * \param op action to be taken on existing conditions, - * \see edg_wll_NotifChangeOp + * \param[in,out] context context to work with + * \param[in] id notification ID you are working with + * \param[in] conditions same as for \ref edg_wll_NotifNew + * \param[in] op action to be taken on existing conditions, + * \ref edg_wll_NotifChangeOp */ int edg_wll_NotifChange( edg_wll_Context context, @@ -89,7 +106,9 @@ int edg_wll_NotifChange( ); /** Refresh the registration, i.e. extend its validity period. - * \param valid until when the registration is valid (NULL means no interest in + * \param[in,out] context context to work with + * \param[in] id notification ID you are working with + * \param[in] valid until when the registration is valid (NULL means no interest in * the value */ @@ -102,6 +121,8 @@ int edg_wll_NotifRefresh( /** Drop the registration. * Server is instructed not to send notifications anymore, pending ones * are discarded, listening socket is closed, and allocated memory freed. + * \param[in,out] context context to work with + * \param[in] id notification ID you are working with */ int edg_wll_NotifDrop( @@ -111,10 +132,12 @@ int edg_wll_NotifDrop( /** Receive notification. * The first incoming notification is returned. - * \param fd receive on this socket (-1 means the default for the context) - * \param timeout wait atmost this time long. (0,0) means polling, NULL waiting + * \param[in,out] context context to work with + * \param[in] fd receive on this socket (-1 means the default for the context) + * \param[in] timeout wait atmost this time long. (0,0) means polling, NULL waiting * indefinitely - * + * \param[out] state_out returned JobStatus + * \param[out] id_out returned NotifId * \retval 0 notification received, state_out contains the current job state * \retval EAGAIN no notification available, timeout occured */ @@ -130,9 +153,10 @@ int edg_wll_NotifReceive( /** Default socket descriptor where to select(2) for notifications. * Even if nothing is available for reading from the socket, - * there may be some data cached so calling \see edg_wll_NotifReceive + * there may be some data cached so calling \ref edg_wll_NotifReceive * may return notifications immediately. * + * \param[in,out] context context to work with * \retval >=0 socket descriptor * \retval -1 error, details set in context */ @@ -142,14 +166,19 @@ int edg_wll_NotifGetFd( ); /** Close the default local listening socket. - * Useful to force following \see edg_wll_NotifBind to open + * Useful to force following \ref edg_wll_NotifBind to open * a new one. + * \param[in,out] context context to work with */ int edg_wll_NotifCloseFd( edg_wll_Context context ); +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/notifid.h b/org.glite.lb.client-interface/interface/notifid.h index fc52d01..3ef1054 100644 --- a/org.glite.lb.client-interface/interface/notifid.h +++ b/org.glite.lb.client-interface/interface/notifid.h @@ -7,21 +7,79 @@ extern "C" { #endif +/** + * \defgroup notifid Notification Id (NotifId) + * \brief NotifId description and handling. + *@{ + */ + /** Notification handle. * Refers to a particular registration for receiving notifications. */ typedef void *edg_wll_NotifId; -/** Parse and unparse the Id. */ -int edg_wll_NotifIdParse(const char *,edg_wll_NotifId *); -char* edg_wll_NotifIdUnparse(const edg_wll_NotifId); +/** + * Create a Job ID. + * \param[in] server notification server hostname + * \param[in] port port of the notification server + * \param[out] notifid newly created NotifId + * \retval 0 for success + * \retval EINVAL invalid notification server + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdCreate(const char *server, int port ,edg_wll_NotifId *notifid); + +/** + * Free the NotifId structure + * \param[in] notifid for dealocation + */ +void edg_wll_NotifIdFree(edg_wll_NotifId notifid); + +/** Parse the NotifId string and creates NotifId structure + * \param[in] notifidstr string representation of NotifId + * \param[out] notifid parsed NotifId + * \retval 0 for success + * \retval EINVAL notifidstr can't be parsed + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdParse(const char *notifidstr, edg_wll_NotifId *notifid); + +/** Unparse the NotifId (produce the string form of NotifId). + * \param[in] notifid NotifId to be converted to string + * \return allocated string which represents the NotifId + */ +char* edg_wll_NotifIdUnparse(const edg_wll_NotifId notifid); + +/** + * Extract notification server address (address:port) + * \param[in] notifid NotifId from which the address should be extracted + * \param[in,out] srvName pointer where to return server name + * \param[in,out] srvPort pointer where to return server port + */ +void edg_wll_NotifIdGetServerParts(const edg_wll_NotifId notifid, char **srvName, unsigned int *srvPort); -int edg_wll_NotifIdCreate(const char *,int,edg_wll_NotifId *); -void edg_wll_NotifIdFree(edg_wll_NotifId); +/** + * Extract unique string + * \param[in] notifid NotifId + * \retval pointer to allocated unique string representing jobid + * \retval NULL if jobid is 0 or memory allocation fails + */ +char *edg_wll_NotifIdGetUnique(const edg_wll_NotifId notifid); -void edg_wll_NotifIdGetServerParts(const edg_wll_NotifId, char **, unsigned int *); -char *edg_wll_NotifIdGetUnique(const edg_wll_NotifId); -int edg_wll_NotifIdSetUnique(edg_wll_NotifId *, const char *); +/** + * Recreate a NotifId by a new unique string + * \param[in] unique string which represent created notifid (if NULL then new + * one is created) + * \param[in,out] notifid newly created NotifId + * \retval 0 success + * \retval EINVAL invalid NotifId + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdSetUnique(edg_wll_NotifId *notifid, const char *unique); + +/* + *@} end of group + */ #ifdef __cplusplus } diff --git a/org.glite.lb.client-interface/interface/producer.h.T b/org.glite.lb.client-interface/interface/producer.h.T index 051eb08..03687a6 100644 --- a/org.glite.lb.client-interface/interface/producer.h.T +++ b/org.glite.lb.client-interface/interface/producer.h.T @@ -93,7 +93,7 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } my $a = "(edg_wll_Context context"; my $b = "(context,EDG_WLL_EVENT_$tu,EDG_WLL_FORMAT_$tu"; my $doc = qq{ - * \\param context\tcontext to work with, + * \\param[in,out] context\tcontext to work with, }; selectType $event $t; for ($event->getFieldsOrdered) { @@ -110,7 +110,7 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } my $fc = $f->getComment; $a = $a . ", $ft $fn"; $b = $b . ", $fn"; - $doc = $doc . " * \\param $fn\t$fc\n"; + $doc = $doc . " * \\param[in] $fn\t$fc\n"; } $a = $a . ")"; $b = $b . ")"; @@ -150,7 +150,8 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } my $e = $doc; $c =~ s/, $ftreg $fn//g; $d =~ s/$fn/"$code"/g; - $e =~ s/ \* \\param $fn\t$fc\n//g; +# FIXME: this documentation line in $e doesn't delete!! + $e =~ s/ \* \\param\[in\] $fn\t$fc\n//g; gen qq{ /** * \\fn int edg_wll_Log$t$code$c; @@ -175,10 +176,10 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } /** * Formats a logging message and sends it asynchronously to local-logger * \brief generic asynchronous logging function - * \param context INOUT context to work with, - * \param event IN type of the event, - * \param fmt IN printf()-like format string, - * \param ... IN event specific values/data according to fmt, + * \param[in,out] context context to work with, + * \param[in] event type of the event, + * \param[in] fmt printf()-like format string, + * \param[in] ... event specific values/data according to fmt, * \retval 0 successful completition, * \retval EINVAL bad jobId, unknown event code, or the format string together with the remaining arguments does not form a valid event, * \retval ENOSPC L&B infrastructure failed to accept the event due to lack of disk space etc., @@ -195,10 +196,10 @@ extern int edg_wll_LogEvent( /** * Formats a logging message and sends it synchronously to local-logger * \brief generic synchronous logging function - * \param context INOUT context to work with, - * \param event IN type of the event, - * \param fmt IN printf()-like format string, - * \param ... IN event specific values/data according to fmt, + * \param[in,out] context context to work with, + * \param[in] event type of the event, + * \param[in] fmt printf()-like format string, + * \param[in] ... event specific values/data according to fmt, * \retval 0 successful completition, * \retval EINVAL bad jobId, unknown event code, or the format string together with the remaining arguments does not form a valid event, * \retval ENOSPC L&B infrastructure failed to accept the event due to lack of disk space etc., @@ -263,10 +264,10 @@ extern int edg_wll_LogFlushAll( /** * Set a current job for given context. * \note Should be called before any logging call. - * \param context INOUT context to work with - * \param job IN further logging calls are related to this job - * \param code IN sequence code as obtained from previous component - * \param flags IN flags on code handling (\see API documentation) + * \param[in,out] context context to work with + * \param[in] job further logging calls are related to this job + * \param[in] code sequence code as obtained from previous component + * \param[in] flags flags on code handling (\see API documentation) */ extern int edg_wll_SetLoggingJob( edg_wll_Context context, @@ -294,6 +295,24 @@ extern int edg_wll_SetLoggingJobProxy( /** + * Set a current job for given context. + * \note Should be called before any logging call. + * \param context INOUT context to work with + * \param job IN further logging calls are related to this job + * \param code IN sequence code as obtained from previous component + * \param user IN user credentials + * \param flags IN flags on code handling (\see API documentation) + */ +extern int edg_wll_SetLoggingJobProxy( + edg_wll_Context context, + const edg_wlc_JobId job, + const char * code, + const char * user, + int flags +); + + +/** * Register job with L&B service. * Done via logging REGJOB event, may generate subjob id's and create * the parent-children associations. @@ -302,15 +321,15 @@ extern int edg_wll_SetLoggingJobProxy( * Partitionable jobs should set num_subjobs=0 initially, * and re-register when number of subjobs becomes known. * - * \param context INOUT context to work with - * \param job IN jobId - * \param type IN EDG_WLL_JOB_SIMPLE, EDG_WLL_JOB_DAG, or EDG_WLL_JOB_PARTITIONABLE - * \param jdl IN user-specified JDL - * \param ns IN network server contact - * \param num_subjobs IN number of subjobs to create - * \param seed IN seed used for subjob id's generator. + * \param[in,out] context context to work with + * \param[in] job jobId + * \param[in] type EDG_WLL_JOB_SIMPLE, EDG_WLL_JOB_DAG, or EDG_WLL_JOB_PARTITIONABLE + * \param[in] jdl user-specified JDL + * \param[in] ns network server contact + * \param[in] num_subjobs number of subjobs to create + * \param[in] seed seed used for subjob id's generator. * Use non-NULL value to be able to regenerate the set of jobid's - * \param subjobs OUT returned subjob id's + * \param[out] subjobs returned subjob id's */ /* backward compatibility */ @@ -351,15 +370,14 @@ extern int edg_wll_RegisterJobSync( * Partitionable jobs should set num_subjobs=0 initially, * and re-register when number of subjobs becomes known. * - * \param context INOUT context to work with - * \param job IN jobId - * \param type IN EDG_WLL_JOB_SIMPLE, EDG_WLL_JOB_DAG, or EDG_WLL_JOB_PARTITIONABLE - * \param jdl IN user-specified JDL - * \param ns IN network server contact - * \param num_subjobs IN number of subjobs to create - * \param seed IN seed used for subjob id's generator. + * \param type IN EDG_WLL_JOB_SIMPLE, EDG_WLL_JOB_DAG, or EDG_WLL_JOB_PARTITIONABLE + * \param user IN user credentials + * \param jdl IN user-specified JDL + * \param ns IN network server contact + * \param num_subjobs IN number of subjobs to create + * \param seed IN seed used for subjob id's generator. * Use non-NULL value to be able to regenerate the set of jobid's - * \param subjobs OUT returned subjob id's + * \param subjobs OUT returned subjob id's */ extern int edg_wll_RegisterJobProxy( @@ -378,11 +396,8 @@ extern int edg_wll_RegisterJobProxy( * Register subjobs in a batch. * Mainly used to provide JDL's of individual subjobs in a more efficient * way than logging them one by one. - * \param context INOUT context to work with - * \param parent IN parent's jobId - * \param jdls IN array of JDL's - * \param ns IN network server contact - * \param subjobs OUT array of jobid's in the same order + * \param jdls array of JDL's + * \param subjobs array of jobid's in the same order */ extern int edg_wll_RegisterSubjobs( @@ -432,15 +447,15 @@ enum edg_wll_UserIdType { /** * Change ACL for given job. - * \param context INOUT context to work with - * \param job IN jobId - * \param user_id IN specification of user's credential - * \param user_id_type IN type of user_id, + * \param[in,out] context context to work with + * \param[in] job jobId + * \param[in] user_id specification of user's credential + * \param[in] user_id_type type of user_id, * for EDG_WLL_USER_SUBJECT the user_id parameter is expected to be user's subject name * for EDG_WLL_USER_VOMS_GROUP the user_id is expected to be of the form VO:group specifying required group membersip as managed by VOMS - * \param permission ACL permission to change - * \param permission_type type of given permission (allow or deny operation) - * \param operation operation to perform with ACL (add or remove record) + * \param[in] permission ACL permission to change + * \param[in] permission_type type of given permission (allow or deny operation) + * \param[in] operation operation to perform with ACL (add or remove record) */ extern int edg_wll_ChangeACL( diff --git a/org.glite.lb.client-interface/interface/statistics.h b/org.glite.lb.client-interface/interface/statistics.h index aceab86..f2444de 100644 --- a/org.glite.lb.client-interface/interface/statistics.h +++ b/org.glite.lb.client-interface/interface/statistics.h @@ -8,14 +8,14 @@ extern "C" { #endif /** Count the number of jobs which entered the specified state. - * \param group IN: group of jobs of interest, eg. DESTINATION = something + * \param[in] group group of jobs of interest, eg. DESTINATION = something * (XXX: this is the only query supported right now) - * \param major IN: major code of the state of interest - * \param minor IN: minor state code, eg. DONE_FAILED - * \param from,to INOUT: on input - requested interval of interest + * \param[in] major major code of the state of interest + * \param[in] minor minor state code, eg. DONE_FAILED + * \param[in,out] from,to on input - requested interval of interest * on output - when the data were available - * \param rate OUT: average rate per second in which the jobs enter this state - * \param res_from, res_to: time resolution of the data (seconds) + * \param[out] rate average rate per second in which the jobs enter this state + * \param[out] res_from,res_to time resolution of the data (seconds) */ int edg_wll_StateRate( diff --git a/org.glite.lb.client-interface/project/configure.properties.xml b/org.glite.lb.client-interface/project/configure.properties.xml index c46c3c6..7145fd1 100644 --- a/org.glite.lb.client-interface/project/configure.properties.xml +++ b/org.glite.lb.client-interface/project/configure.properties.xml @@ -20,9 +20,32 @@ Revision history: $Log$ + Revision 1.4 2005/02/25 09:37:43 mmulac + generate doxygen doc for notification.h + Revision 1.3 2005/01/17 11:40:09 jpospi Documentation update. + Revision 1.2.2.6 2005/02/25 18:12:17 jpospi + Added MACRO_EXPANSION option to doxygen conf to be able to expand _EDG_WLL_EVENT_COMMON in the generated documentation. + + Revision 1.2.2.5 2005/02/25 13:39:29 mmulac + remove duplicate notifid in configure.properties.xml + + Revision 1.2.2.4 2005/02/25 13:37:11 mmulac + add notifid to doxygen + see -> ref + + Revision 1.2.2.3 2005/02/25 12:03:11 jpospi + Added PDF options to doxygen conf. + + Revision 1.2.2.2 2005/02/25 09:37:52 mmulac + generate doxygen doc for notification.h + + Revision 1.2.2.1 2005/02/18 14:00:16 jpospi + - Removed all L&B Proxy related things + - Documentation update + Revision 1.2 2004/12/08 13:04:29 jpospi first attemtp to generate documentation using doxygen @@ -69,12 +92,18 @@ INPUT = ./events.h \ ./jobstat.h \ ./producer.h \ ../interface/context.h \ + ../interface/notifid.h \ ../interface/notification.h \ ../interface/consumer.h -SHOW_DIRECTORIES = NO -EXTRACT_ALL = YES -#HAVE_DOT = YES -#CALL_GRAPH = YES +SHOW_DIRECTORIES = NO +FULL_PATH_NAMES = NO +EXTRACT_ALL = YES +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = _EDG_WLL_EVENT_COMMON +HAVE_DOT = NO PROJECT_NAME = "Glite LB Client: CPP - Interface" @@ -88,7 +117,10 @@ INPUT = ../build/Event.h \ ../interface/ServerConnection.h \ ../interface/Notification.h SHOW_DIRECTORIES = NO +FULL_PATH_NAMES = NO EXTRACT_ALL = YES +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES #HAVE_DOT = YES #CALL_GRAPH = YES diff --git a/org.glite.lb.client/Makefile b/org.glite.lb.client/Makefile index 4aaccb3..a2bd8a4 100644 --- a/org.glite.lb.client/Makefile +++ b/org.glite.lb.client/Makefile @@ -137,7 +137,8 @@ PLUSLIB:=libglite_lb_clientpp_${nothrflavour}.la THRPLUSLIB:=libglite_lb_clientpp_${thrflavour}.la TOOLS:=dump load purge -EXAMPLES:=log_usertag_proxy job_log job_reg feed_shark notify query_ext query_seq_code stats abort_job +EXAMPLES:=log_usertag_proxy job_log job_reg feed_shark notify query_ext query_seq_code stats abort_job change_acl + EXAMPLES_CL=user_jobs job_status FAKE_EXAMPLES:=job_log_fake diff --git a/org.glite.lb.client/examples/change_acl.c b/org.glite.lb.client/examples/change_acl.c new file mode 100644 index 0000000..eb731cf --- /dev/null +++ b/org.glite.lb.client/examples/change_acl.c @@ -0,0 +1,78 @@ +#ident "$Header$" + +#include +#include + +#include "glite/wmsutils/jobid/cjobid.h" +#include "glite/lb/producer.h" +#include "glite/lb/authz.h" + +void +usage(const char *me) +{ + fprintf(stderr,"usage: %s [-r] [-d] [-g] jobid user_id\n" + "\t-r \tRemove\n" + "\t-d \tOperation is considered as `allow' by default, if -d is given 'deny' will be used\n" + "\t-g \tuser_id is treated as DN by default, if -g is given user_id is expectedto be of form VO:group\n", + + me); +} + +int +main(int argc, char *argv[]) +{ + edg_wll_Context ctx; + int operation = EDG_WLL_ACL_ADD; + int permission = EDG_WLL_PERM_READ; + int permission_type = EDG_WLL_PERM_ALLOW; + int user_id_type = EDG_WLL_USER_SUBJECT; + edg_wlc_JobId jobid; + int opt; + int ret; + + if (argc < 3) { + usage(argv[0]); + return 1; + } + + while ((opt=getopt(argc, argv, "rdg")) != -1) + switch(opt) { + case 'r': operation = EDG_WLL_ACL_REMOVE; break; + case 'd': permission_type = EDG_WLL_PERM_DENY; break; + case 'g': user_id_type = EDG_WLL_USER_VOMS_GROUP; break; + default: + usage(argv[0]); + return 1; + break; + } + + edg_wll_InitContext(&ctx); + + if (edg_wlc_JobIdParse(argv[optind], &jobid)) { + fprintf(stderr,"can't parse job ID\n"); + goto err; + } + + edg_wll_SetParam(ctx, EDG_WLL_PARAM_SOURCE, EDG_WLL_SOURCE_USER_INTERFACE); + + ret = edg_wll_ChangeACL(ctx, + jobid, + argv[optind+1], user_id_type, + permission, permission_type, + operation); + + if (ret) { + char *et, *ed; + edg_wll_Error(ctx, &et, &ed); + fprintf(stderr, "%s: edg_wll_LogChangeACL() failed: %s (%s)\n", + argv[0], et, ed); + goto err; + } + + edg_wll_FreeContext(ctx); + return 0; + +err: + edg_wll_FreeContext(ctx); + return 1; +} diff --git a/org.glite.lb.client/examples/job_log.c b/org.glite.lb.client/examples/job_log.c index ca1c09e..4d7a550 100644 --- a/org.glite.lb.client/examples/job_log.c +++ b/org.glite.lb.client/examples/job_log.c @@ -44,7 +44,7 @@ int main(int argc,char **argv) { edg_wll_Context ctx; char *errt,*errd; - edg_wll_Event *events; + edg_wll_Event *events = NULL; edg_wlc_JobId job; int i,opt,delay = 1,count = 0; @@ -71,13 +71,10 @@ int main(int argc,char **argv) if ( edg_wll_JobLog(ctx,job,&events) ) { - if ( edg_wll_Error(ctx, &errt, &errd) != E2BIG ) - goto err; - fprintf(stderr,"%s: %s (%s)\n",argv[0],errt,errd); } - for ( i = 0; events[i].type != EDG_WLL_EVENT_UNDEF; i++ ) + for ( i = 0; events && events[i].type != EDG_WLL_EVENT_UNDEF; i++ ) { char *e = edg_wll_UnparseEvent(ctx,events+i); fputs(e,stdout); diff --git a/org.glite.lb.client/src/ServerConnection.cpp b/org.glite.lb.client/src/ServerConnection.cpp index 319bd0f..ad5eaa1 100644 --- a/org.glite.lb.client/src/ServerConnection.cpp +++ b/org.glite.lb.client/src/ServerConnection.cpp @@ -547,36 +547,69 @@ ServerConnection::setQueryJobsLimit(int max) { std::pair ServerConnection::getQueryServer() const { - /* FIXME: not implemented in C API */ - STACK_ADD; - throw Exception(EXCEPTION_MANDATORY, 0, "method not implemented"); + char *hostname; + int port; + + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_QUERY_SERVER, + &hostname), + context, + "getting query server address"); + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_QUERY_SERVER_PORT, + &port), + context, + "getting query server port"); + return std::pair(std::string(strdup(hostname)), port); } int ServerConnection::getQueryTimeout() const { - /* FIXME: not implemented in C API */ - STACK_ADD; - throw Exception(EXCEPTION_MANDATORY, 0, "method not implemented"); + int timeout; + + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_QUERY_TIMEOUT, + &timeout), + context, + "getting query timeout"); + return timeout; } std::string ServerConnection::getX509Proxy() const { - /* FIXME: not implemented in C API */ - STACK_ADD; - throw Exception(EXCEPTION_MANDATORY, 0, "method not implemented"); + char *proxy; + + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_X509_PROXY, + &proxy), + context, + "getting X509 proxy"); + return std::string(strdup(proxy)); } std::pair ServerConnection::getX509Cert() const { - /* FIXME: not implemented in C API */ - STACK_ADD; - throw Exception(EXCEPTION_MANDATORY, 0, "method not implemented"); + char *cert, *key; + + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_X509_CERT, + &cert), + context, + "getting X509 cert"); + check_result(edg_wll_GetParam(context, + EDG_WLL_PARAM_X509_KEY, + &key), + context, + "getting X509 key"); + + return std::pair(std::string(strdup(cert)), + std::string(strdup(key))); } // static @@ -650,7 +683,7 @@ edg_wll_QueryRec ** convertQueryVectorExt(const std::vector > &in) { unsigned i; - edg_wll_QueryRec **out = new (edg_wll_QueryRec*)[in.size() + 1]; + edg_wll_QueryRec **out = new edg_wll_QueryRec*[in.size() + 1]; if(out == NULL) { STACK_ADD; @@ -1253,7 +1286,7 @@ void ServerConnection::setParam(edg_wll_ContextParam par, int val) "edg_wll_SetParamInt()"); } -void ServerConnection::setParam(edg_wll_ContextParam par, const std::string val) +void ServerConnection::setParam(edg_wll_ContextParam par, const std::string &val) { check_result(edg_wll_SetParamString(context,par,val.c_str()), context, diff --git a/org.glite.lb.client/src/connection.c b/org.glite.lb.client/src/connection.c index c9b2b15..33fdf78 100644 --- a/org.glite.lb.client/src/connection.c +++ b/org.glite.lb.client/src/connection.c @@ -10,6 +10,7 @@ #include #include #include +#include #include "glite/security/glite_gss.h" #include "glite/lb/consumer.h" @@ -23,6 +24,9 @@ static void CloseConnection(edg_wll_Context ctx, int conn_index) /* close connection ad free its structures */ OM_uint32 min_stat; + assert(ctx->connOpened); + assert(conn_index < ctx->connOpened); + edg_wll_gss_close(&ctx->connPool[conn_index].gss, &ctx->p_tmp_timeout); if (ctx->connPool[conn_index].gsiCred) gss_release_cred(&min_stat, &ctx->connPool[conn_index].gsiCred); @@ -98,9 +102,11 @@ static void ReleaseConnection(edg_wll_Context ctx, char *name, int port) int edg_wll_close(edg_wll_Context ctx) { edg_wll_ResetError(ctx); + if (ctx->connToUse == -1) return 0; CloseConnection(ctx, ctx->connToUse); + ctx->connToUse = -1; return edg_wll_Error(ctx,NULL,NULL); } @@ -185,6 +191,7 @@ err: /* some error occured; close created connection * and free all fields in connPool[index] */ CloseConnection(ctx, index); + ctx->connToUse = -1; ok: return edg_wll_Error(ctx,NULL,NULL); } @@ -294,6 +301,9 @@ int edg_wll_http_send_recv( char ***resp_head, char **resp_body) { + int ec; + char *ed = NULL; + if (edg_wll_open(ctx)) return edg_wll_Error(ctx,NULL,NULL); switch (edg_wll_http_send(ctx,request,req_head,req_body)) { @@ -301,22 +311,34 @@ int edg_wll_http_send_recv( edg_wll_close(ctx); if (edg_wll_open(ctx) || edg_wll_http_send(ctx,request,req_head,req_body)) - return edg_wll_Error(ctx,NULL,NULL); + goto err; /* fallthrough */ case 0: break; - default: return edg_wll_Error(ctx,NULL,NULL); + default: goto err; } - if (edg_wll_http_recv(ctx,response,resp_head,resp_body) == ENOTCONN) { - edg_wll_close(ctx); - (void) (edg_wll_open(ctx) - || edg_wll_http_send(ctx,request,req_head,req_body) - || edg_wll_http_recv(ctx,response,resp_head,resp_body)); + switch (edg_wll_http_recv(ctx,response,resp_head,resp_body)) { + case ENOTCONN: + edg_wll_close(ctx); + if (edg_wll_open(ctx) + || edg_wll_http_send(ctx,request,req_head,req_body) + || edg_wll_http_recv(ctx,response,resp_head,resp_body)) + goto err; + /* fallthrough */ + case 0: break; + default: goto err; } + assert(ctx->connToUse >= 0); gettimeofday(&ctx->connPool[ctx->connToUse].lastUsed, NULL); - - return edg_wll_Error(ctx,NULL,NULL); + return 0; + +err: + ec = edg_wll_Error(ctx,NULL,&ed); + edg_wll_close(ctx); + edg_wll_SetError(ctx,ec,ed); + free(ed); + return ec; } diff --git a/org.glite.lb.common/build.xml b/org.glite.lb.common/build.xml index c2b7167..e3add29 100755 --- a/org.glite.lb.common/build.xml +++ b/org.glite.lb.common/build.xml @@ -20,6 +20,12 @@ Revision history: $Log$ + Revision 1.7 2005/05/26 15:13:46 zurek + inserted module.build.file + + Revision 1.6.2.1 2005/02/12 01:39:00 glbuild + Changed start time + Revision 1.6 2004/10/18 19:16:09 zsalvet RPM descriptions diff --git a/org.glite.lb.common/interface/log_proto.h b/org.glite.lb.common/interface/log_proto.h index 0e4e6cf..0dfbbc8 100644 --- a/org.glite.lb.common/interface/log_proto.h +++ b/org.glite.lb.common/interface/log_proto.h @@ -3,7 +3,6 @@ #ident "$Header$" - /** * \file edg/workload/logging/common/log_proto.h * \brief common part of the logging protocol diff --git a/org.glite.lb.common/src/context.c b/org.glite.lb.common/src/context.c index 1e37089..7978a9e 100644 --- a/org.glite.lb.common/src/context.c +++ b/org.glite.lb.common/src/context.c @@ -34,6 +34,7 @@ int edg_wll_InitContext(edg_wll_Context *ctx) out->connPoolNotif = (edg_wll_ConnPool *) calloc(1, sizeof(edg_wll_ConnPool)); out->connProxy = (edg_wll_ConnPool *) calloc(1, sizeof(edg_wll_ConnProxy)); out->connProxy->conn.sock = -1; + out->connToUse = -1; *ctx = out; return 0; diff --git a/org.glite.lb.common/src/events.c.T b/org.glite.lb.common/src/events.c.T index 3d0861a..4ceee87 100644 --- a/org.glite.lb.common/src/events.c.T +++ b/org.glite.lb.common/src/events.c.T @@ -31,14 +31,14 @@ for my $e (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } }; /** - * \fn edg_wll_EventCode edg_wll_StringToEvent(char *name) + * \fn edg_wll_EventCode edg_wll_StringToEvent(const char *name) * \param name a string event name (e.g. "JobTransfer") * \return corresponding numeric code (edg_wll_EventCode) * \brief convert a string event name to the corresponding numeric code * Calls: strcasecmp * Algorithm: array lookup */ -edg_wll_EventCode edg_wll_StringToEvent(char *name) +edg_wll_EventCode edg_wll_StringToEvent(const char *name) { unsigned int i; @@ -95,14 +95,14 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } }; /* - * \fn edg_wll_KeyNameCode edg_wll_StringToKeyName(char *name) + * \fn edg_wll_KeyNameCode edg_wll_StringToKeyName(const char *name) * \param name a string ULM key name (e.g. "DG.JOB.TRANSFER.DEST") * \return corresponding numeric code (edg_wll_KeyNameCode) * \brief convert a string ULM key name to the corresponding numeric code * Calls: strcasecmp * Algorithm: array lookup */ -edg_wll_KeyNameCode edg_wll_StringToKeyName(char *name) +edg_wll_KeyNameCode edg_wll_StringToKeyName(const char *name) { unsigned int i; @@ -156,11 +156,11 @@ static const char \*${char}\[\] = \{ # function StringTo: gen qq{ /** - * \\fn $enum edg_wll_StringTo${c}(char *name) + * \\fn $enum edg_wll_StringTo${c}(const char *name) * Calls: strcasecmp * Algorithm: array lookup */ -$enum edg_wll_StringTo${c}(char *name) +$enum edg_wll_StringTo${c}(const char *name) \{ unsigned int i; @@ -212,11 +212,11 @@ static const char \*${char}\[\] = \{ # function StringTo: gen qq{ /** - * \\fn $enum edg_wll_StringTo${c}(char *name) + * \\fn $enum edg_wll_StringTo${c}(const char *name) * Calls: strcasecmp * Algorithm: array lookup */ -$enum edg_wll_StringTo${c}(char *name) +$enum edg_wll_StringTo${c}(const char *name) \{ unsigned int i; @@ -338,6 +338,12 @@ for my $t (sort { $event->{order}->{$a} <=> $event->{order}->{$b} } if ($ft eq 'string') { gen $indent."\tif (event->$tl.$fn) free(event->$tl.$fn);\n" } + if ($ft eq 'jobid') { + gen $indent."\tif (event->$tl.$fn) edg_wlc_JobIdFree(event->$tl.$fn);\n" + } + if ($ft eq 'notifid') { + gen $indent."\tif (event->$tl.$fn) edg_wll_NotifIdFree(event->$tl.$fn);\n" + } } gen $indent.$indent."break;\n" } diff --git a/org.glite.lb.common/src/param.c b/org.glite.lb.common/src/param.c index 253e241..b649fe4 100644 --- a/org.glite.lb.common/src/param.c +++ b/org.glite.lb.common/src/param.c @@ -19,57 +19,70 @@ static const char *myenv[] = { NULL, NULL, NULL, - "EDG_WL_LOG_DESTINATION", - "EDG_WL_LOG_DESTINATION", - "EDG_WL_LOG_TIMEOUT", - "EDG_WL_LOG_SYNC_TIMEOUT", - "EDG_WL_QUERY_SERVER", - "EDG_WL_QUERY_SERVER", - "EDG_WL_QUERY_SERVER_OVERRIDE", - "EDG_WL_QUERY_TIMEOUT", - "EDG_WL_QUERY_JOBS_LIMIT", - "EDG_WL_QUERY_EVENTS_LIMIT", - "EDG_WL_QUERY_RESULTS", - "EDG_WL_QUERY_CONNECTIONS", - "EDG_WL_NOTIF_SERVER", - "EDG_WL_NOTIF_SERVER", - "EDG_WL_NOTIF_TIMEOUT", + "%sLOG_DESTINATION", + "%sLOG_DESTINATION", + "%sLOG_TIMEOUT", + "%sLOG_SYNC_TIMEOUT", + "%sQUERY_SERVER", + "%sQUERY_SERVER", + "%sQUERY_SERVER_OVERRIDE", + "%sQUERY_TIMEOUT", + "%sQUERY_JOBS_LIMIT", + "%sQUERY_EVENTS_LIMIT", + "%sQUERY_RESULTS", + "%sQUERY_CONNECTIONS", + "%sNOTIF_SERVER", + "%sNOTIF_SERVER", + "%sNOTIF_TIMEOUT", /* don't care about X509_USER_*, GSI looks at them anyway */ NULL, NULL, NULL, - "EDG_WL_LBPROXY_STORE_SOCK", - "EDG_WL_LBPROXY_SERVE_SOCK", - "EDG_WL_LBPROXY_USER", - "EDG_WL_JPREG_TMPDIR", + "%sLBPROXY_STORE_SOCK", + "%sLBPROXY_SERVE_SOCK", + "%sLBPROXY_USER", + "%sJPREG_TMPDIR", }; /* XXX: does not parse URL, just hostname[:port] */ -static int extract_port(edg_wll_ContextParam param,int dflt) +static char *mygetenv(int param) { - char *p = NULL,*s = NULL; + char *s = NULL; + if (myenv[param]) { - s = getenv(myenv[param]); - if (s) p = strchr(s,':'); + char varname[100]; + + sprintf(varname,myenv[param],"GLITE_WMS_"); + s = getenv(varname); + + if (!s) { + sprintf(varname,myenv[param],"EDG_WL_"); + s = getenv(varname); + } } + return s; +} + +static int extract_port(edg_wll_ContextParam param,int dflt) +{ + char *p = NULL,*s = mygetenv(param); + + if (s) p = strchr(s,':'); return p ? atoi(p+1) : dflt; } static int extract_num(edg_wll_ContextParam param,int dflt) { - if (myenv[param]) { - char *s = getenv(myenv[param]); - if (s) return(atoi(s)); - } - return dflt; + char *s = mygetenv(param); + return s ? atoi(s) : dflt; } static char *extract_host(edg_wll_ContextParam param,const char *dflt) { char *p,*s = NULL; - if (myenv[param]) s = getenv(myenv[param]); + s = mygetenv(param); if (!s && !dflt) return NULL; s = strdup(s?s:dflt), p = strchr(s,':'); @@ -82,7 +95,7 @@ static void extract_time(edg_wll_ContextParam param,double dflt,struct timeval * char *s = NULL; double d; - if (myenv[param]) s = getenv(myenv[param]); + s = mygetenv(param); d = s ? atof(s) : dflt; t->tv_sec = (long) d; t->tv_usec = (long) ((d-t->tv_sec)*1e6); @@ -93,8 +106,7 @@ static char *extract_split(edg_wll_ContextParam param,char by,int index) int i; char *s,*e; - if (!myenv[param]) return NULL; - if (!(s = getenv(myenv[param]))) return NULL; + if (!(s = mygetenv(param))) return NULL; for (i=0; ip_cert_filename = val ? strdup(val) : NULL; break; case EDG_WLL_PARAM_QUERY_SERVER_OVERRIDE: - if (!val) val = getenv(myenv[param]); + if (!val) val = mygetenv(param); if (!val) val = "no"; ctx->p_query_server_override = !strcasecmp(val,"yes"); break; @@ -218,7 +230,7 @@ int edg_wll_SetParamInt(edg_wll_Context ctx,edg_wll_ContextParam param,int val) break; case EDG_WLL_PARAM_QUERY_CONNECTIONS: { - char *s = getenv(myenv[param]); + char *s = mygetenv(param); if (!val && s) val = atoi(s); ctx->poolSize = val ? val : EDG_WLL_LOG_CONNECTIONS_DEFAULT; diff --git a/org.glite.lb.logger/build.xml b/org.glite.lb.logger/build.xml index 6ecb2d7..e5382ce 100755 --- a/org.glite.lb.logger/build.xml +++ b/org.glite.lb.logger/build.xml @@ -20,6 +20,12 @@ Revision history: $Log$ + Revision 1.5 2005/05/26 15:13:49 zurek + inserted module.build.file + + Revision 1.4.2.1 2005/02/12 01:39:10 glbuild + Changed start time + Revision 1.4 2004/10/18 19:16:09 zsalvet RPM descriptions diff --git a/org.glite.lb.logger/src/event_store.c b/org.glite.lb.logger/src/event_store.c index 3ee97f3..9f56219 100644 --- a/org.glite.lb.logger/src/event_store.c +++ b/org.glite.lb.logger/src/event_store.c @@ -343,29 +343,74 @@ event_store_recover(struct event_store *es) return(-1); } - /* get the position in file to be sought */ - if(es->offset) - last = es->offset; - else { + while(1) { /* try, try, try */ + + /* get the position in file to be sought */ + if(es->offset) + last = es->offset; + else { #if !defined(IL_NOTIFICATIONS) - if(eq_b == eq_l) - last = es->last_committed_ls; - else + if(eq_b == eq_l) + last = es->last_committed_ls; + else #endif - /* last = min(ls, bs) */ - last = (es->last_committed_bs < es->last_committed_ls) ? es->last_committed_bs : es->last_committed_ls; - } - - il_log(LOG_DEBUG, " setting starting file position to %ld\n", last); - il_log(LOG_DEBUG, " bytes sent to logging server: %d\n", es->last_committed_ls); - il_log(LOG_DEBUG, " bytes sent to bookkeeping server: %d\n", es->last_committed_bs); + /* last = min(ls, bs) */ + /* I took the liberty to optimize this, + since LS is not used. */ + /* last = (es->last_committed_bs < + es->last_committed_ls) ? es->last_committed_bs : + es->last_committed_ls; */ + last = es->last_committed_bs; + } - /* skip all committed or already enqueued events */ - if(fseek(ef, last, SEEK_SET) < 0) { - set_error(IL_SYS, errno, "event_store_recover: error setting position for read"); - event_store_unlock(es); - fclose(ef); - return(-1); + il_log(LOG_DEBUG, " setting starting file position to %ld\n", last); + il_log(LOG_DEBUG, " bytes sent to logging server: %d\n", es->last_committed_ls); + il_log(LOG_DEBUG, " bytes sent to bookkeeping server: %d\n", es->last_committed_bs); + + if(last > 0) { + int c; + + /* skip all committed or already enqueued events */ + /* be careful - check, if the offset really points to the + beginning of event string */ + if(fseek(ef, last-1, SEEK_SET) < 0) { + set_error(IL_SYS, errno, "event_store_recover: error setting position for read"); + event_store_unlock(es); + fclose(ef); + return(-1); + } + /* the last enqueued event MUST end with EVENT_SEPARATOR, + even if the offset points at EOF */ + if((c=fgetc(ef)) != EVENT_SEPARATOR) { + /* Houston, we have got a problem */ + il_log(LOG_WARNING, + " file position %ld does not point at the beginning of event string, backing off!\n", + last); + /* now, where were we? */ + if(es->offset) { + /* next try will be with + last_commited_bs */ + es->offset = 0; + } else { + /* this is really weird... back off completely */ + es->last_committed_ls = es->last_committed_bs = 0; + } + } else { + /* OK, break out of the loop */ + break; + } + } else { + /* this breaks out of the loop, we are starting at + * the beginning of file + */ + if(fseek(ef, 0, SEEK_SET) < 0) { + set_error(IL_SYS, errno, "event_store_recover: error setting position for read"); + event_store_unlock(es); + fclose(ef); + return(-1); + } + break; + } } /* enqueue all remaining events */ @@ -383,7 +428,8 @@ event_store_recover(struct event_store *es) msg = server_msg_create(event_s, last); free(event_s); if(msg == NULL) { - break; + il_log(LOG_ALERT, " event file corrupted! Please move it to quarantine (ie. somewhere else) and restart interlogger.\n"); + break; } msg->es = es; diff --git a/org.glite.lb.server-bones/Makefile b/org.glite.lb.server-bones/Makefile index 926a6df..7b01dee 100644 --- a/org.glite.lb.server-bones/Makefile +++ b/org.glite.lb.server-bones/Makefile @@ -50,7 +50,7 @@ ${LTLIB}: ${LOBJS} ${LINK} -o $@ ${LOBJS} stage: compile - $(MAKE) install PREFIX=${stagedir} + $(MAKE) install PREFIX=${stagedir} DOSTAGE=yes check: -echo "No unit tests so far." @@ -81,9 +81,11 @@ distbin: install: mkdir -p ${PREFIX}/include/${globalprefix}/${lbprefix} mkdir -p ${PREFIX}/lib - ${INSTALL} -m 644 ${STATICLIB} ${PREFIX}/lib ${INSTALL} -m 644 ${LTLIB} ${PREFIX}/lib - cd ${top_srcdir}/interface && install -m 644 ${HDRS} ${PREFIX}/include/${globalprefix}/${lbprefix} + if [ x${DOSTAGE} = xyes ]; then \ + ${INSTALL} -m 644 ${STATICLIB} ${PREFIX}/lib ; \ + cd ${top_srcdir}/interface && install -m 644 ${HDRS} ${PREFIX}/include/${globalprefix}/${lbprefix} ; \ + fi clean: diff --git a/org.glite.lb.server/Makefile b/org.glite.lb.server/Makefile index 47c7e53..9147b02 100644 --- a/org.glite.lb.server/Makefile +++ b/org.glite.lb.server/Makefile @@ -20,6 +20,8 @@ gsoap_prefix=/opt/gsoap -include Makefile.inc +default all: compile + GLITE_LB_SERVER_WITH_WS=yes ifeq ($(GLITE_LB_SERVER_WITH_WS),yes) @@ -75,7 +77,11 @@ GLOBUS_LIBS:= -L${globus_prefix}/lib \ -lglobus_gssapi_gsi_${nothrflavour} \ ifneq (${mysql_prefix},/usr) - myslqlib := -L${mysql_prefix}/lib/mysql + ifeq ($(shell echo ${mysql_version} | cut -d. -f1,2),4.1) + mysqlib := -L${mysql_prefix}/lib/mysql + else + mysqlib := -L${mysql_prefix}/lib + endif endif ifneq (${expat_prefix},/usr) @@ -91,7 +97,7 @@ ifeq (${nothrflavour},gcc32dbg) endif EXT_LIBS:= -L${ares_prefix}/lib -lares \ - ${myslqlib} -lmysqlclient -lz\ + ${mysqlib} -lmysqlclient -lz\ ${expatlib} -lexpat \ ${GRIDSITE_LIBS} \ -lvomsc${vomsflavour} \ diff --git a/org.glite.lb.server/build.xml b/org.glite.lb.server/build.xml index c99075a..ca199d2 100755 --- a/org.glite.lb.server/build.xml +++ b/org.glite.lb.server/build.xml @@ -20,6 +20,12 @@ Revision history: $Log$ + Revision 1.5 2005/05/26 15:13:55 zurek + inserted module.build.file + + Revision 1.4.2.1 2005/02/12 01:39:21 glbuild + Changed start time + Revision 1.4 2004/10/18 19:16:09 zsalvet RPM descriptions diff --git a/org.glite.lb.server/project/configure.properties.xml b/org.glite.lb.server/project/configure.properties.xml index 25ec0ca..ffe0fff 100644 --- a/org.glite.lb.server/project/configure.properties.xml +++ b/org.glite.lb.server/project/configure.properties.xml @@ -20,9 +20,15 @@ Revision history: $Log$ + Revision 1.6 2005/01/21 11:27:44 jpospi + completely remove gridsite.prefix and voms.prefix + Revision 1.5 2005/01/20 11:43:00 jpospi handle correctly gridsite_prefix and voms_prefix + Revision 1.4.2.1 2005/05/19 13:41:22 akrenek + fix build with mysql 4.1.x + Revision 1.4 2004/10/15 11:03:03 jskrabal - merge fixes @@ -76,6 +82,7 @@ nothrflavour=${with.globus.nothr.flavor} expat_prefix=${with.expat.prefix} ares_prefix=${with.ares.prefix} mysql_prefix=${with.mysql.prefix} +mysql_version=${ext.mysql.version} cppunit=${with.cppunit.prefix} gsoap_prefix=${with.gsoap.prefix} diff --git a/org.glite.lb.server/src/dump.c b/org.glite.lb.server/src/dump.c index afe262a..e14a55c 100644 --- a/org.glite.lb.server/src/dump.c +++ b/org.glite.lb.server/src/dump.c @@ -23,13 +23,14 @@ #include "server_state.h" #include "purge.h" +static char *time_to_string(time_t t, char **ptr); static int handle_specials(edg_wll_Context,time_t *); #define sizofa(a) (sizeof(a)/sizeof((a)[0])) int edg_wll_DumpEvents(edg_wll_Context ctx,const edg_wll_DumpRequest *req,edg_wll_DumpResult *result) { - char *from_s, *to_s, *stmt, *time_s; + char *from_s, *to_s, *stmt, *time_s, *ptr; char *tmpfname; time_t start,end; edg_wll_Stmt q = NULL; @@ -130,13 +131,13 @@ int edg_wll_DumpEvents(edg_wll_Context ctx,const edg_wll_DumpRequest *req,edg_wl } time(&end); - time_s = strdup(edg_wll_TimeToDB(start)); + time_s = time_to_string(start, &ptr); edg_wll_SetServerState(ctx,EDG_WLL_STATE_DUMP_START,time_s); - free(time_s); + free(ptr); - time_s = strdup(edg_wll_TimeToDB(end)); + time_s = time_to_string(end, &ptr); edg_wll_SetServerState(ctx,EDG_WLL_STATE_DUMP_END,time_s); - free(time_s); + free(ptr); result->from = from; result->to = to; @@ -187,3 +188,12 @@ static int handle_specials(edg_wll_Context ctx,time_t *t) } +static char *time_to_string(time_t t, char **ptr) { + char *s; + + s = edg_wll_TimeToDB(t); + s[strlen(s) - 1] = '\0'; + *ptr = s; + + return s + 1; +} diff --git a/org.glite.lb.server/src/server_state.c b/org.glite.lb.server/src/server_state.c index 80a1316..d2bf8f0 100644 --- a/org.glite.lb.server/src/server_state.c +++ b/org.glite.lb.server/src/server_state.c @@ -32,7 +32,7 @@ int edg_wll_SetServerState(edg_wll_Context ctx,const char *name,const char *val) char *stmt = NULL; trio_asprintf(&stmt,"insert into server_state (prefix,name,value) " - "values ('https://%|Ss:%d','%|Ss',%s)", + "values ('https://%|Ss:%d','%|Ss','%|Ss')", ctx->srvName,ctx->srvPort,name,val); switch(edg_wll_ExecStmt(ctx,stmt,NULL)) { diff --git a/org.glite.lb.server/src/srv_purge.c b/org.glite.lb.server/src/srv_purge.c index 39179cd..a2068dc 100644 --- a/org.glite.lb.server/src/srv_purge.c +++ b/org.glite.lb.server/src/srv_purge.c @@ -65,7 +65,8 @@ int edg_wll_CreateTmpFileStorage(edg_wll_Context ctx, char *prefix, char **fname char buff[100]; sprintf(buff, "couldn't create temporary server file"); - return edg_wll_SetError(ctx, errno, buff); + edg_wll_SetError(ctx, errno, buff); + return -1; } } else -- 1.8.2.3