From 837193bea8019ad9201f3b0587bf35eb88a8305d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ale=C5=A1=20K=C5=99enek?= Date: Fri, 4 Apr 2008 07:20:34 +0000 Subject: [PATCH] - print available fields - manpage --- org.glite.lb.client/Makefile | 2 +- org.glite.lb.client/doc/glite-lb-notify.1 | 127 ++++++++++++++++++++++++++++++ org.glite.lb.client/src/notify.c | 6 +- org.glite.lb.client/src/notify_supp.cpp | 15 ++++ org.glite.lb.client/src/notify_supp.h | 2 + 5 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 org.glite.lb.client/doc/glite-lb-notify.1 diff --git a/org.glite.lb.client/Makefile b/org.glite.lb.client/Makefile index ee711aa..a36a170 100644 --- a/org.glite.lb.client/Makefile +++ b/org.glite.lb.client/Makefile @@ -150,7 +150,7 @@ EXAMPLES_CL:=${EXAMPLES_CL_SRC:.c=} EXAMPLES_CL_THR_SRC:=user_jobs_threaded.c EXAMPLES_CL_THR:=${EXAMPLES_CL_THR_SRC:.c=} -MAN_GZ:=glite-lb-logevent.1.gz +MAN_GZ:=glite-lb-logevent.1.gz glite-lb-notify.1.gz MAN8_GZ:=glite-lb-dump.8.gz glite-lb-load.8.gz glite-lb-purge.8.gz MAN = $(MAN_GZ:.gz=) MAN8 = $(MAN8_GZ:.gz=) diff --git a/org.glite.lb.client/doc/glite-lb-notify.1 b/org.glite.lb.client/doc/glite-lb-notify.1 new file mode 100644 index 0000000..3b01fa2 --- /dev/null +++ b/org.glite.lb.client/doc/glite-lb-notify.1 @@ -0,0 +1,127 @@ +.TH GLITE-LB-NOTIFY 1 "Apr 2008" "EU EGEE Project" "Logging&Bookkeeping" + +.SH NAME +glite-lb-notify - Register and receive notification from L&B + +.SH SYNOPSIS +.B glite-lb-notify +.br + \fBnew\fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] { \fB-j \fIjobid \fR| \fB-o \fIowner \fR| \fB-n \fInetwork_server \fR| \fB-v\fI virtual_organization\fR } +.br + \fBbind \fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] \fInotifid\fR +.br + \fBrefresh\fR [ \fB-t \fIrequested_validity \fR ] notifid +.br + \fBreceive\fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] [ \fB -i \fItimeout \fR] [ \fB-f\fI field1,field2\fR,... \fInotifid\fR +.br + \fBdrop\fR \fInotifid\fR + + +.SH DESCRIPTION +.B glite-lb-notify +is a fairly simple wrapper on the L&B notification API. +It allows to create a notification (with a restricted richness of specifying +conditions), bind to it for receiving notifications, and drop it finally. + +L&B notification is a user-initiated trigger at the server. +Whenever a job enters a state matching conditions specified with the notification, +the current state of the job is sent to the notification client. +On the other hand, the notification client is a network listener +which receives server-initiated connections to get the notifications. +Unless +.B -s +is specified, the notification library creates the listener +socket. + +Within the notification validity, +clients can disappear and even migrate. +However, only a single active client for a notification is allowed. + +This command +is intended to be used in user scripts, graphical tools etc. where +direct access to the API is difficult. + +L&B server and port to contact is specified with GLITE_WMS_NOTIF_SERVER environment +variable. + +.SH USAGE +Common options (mostly) +.TP +.B -t +specifies a requested validity of the notification (in seconds of UNIX Epoch), +the server can truncate the value according to its policy. +.TP +.B -a +allows to specify a fake listener address to register with the notification, +i.e. to overcome firewalls etc. +When notifications are delivered, the server tries to connect to this +address rather than the true address of the listening socket. +Requires re-binding therefore it +can't be used in conjunction with +.B -s +. +.TP +.B -s +allows to pass a opened listening socket (filedescriptor number), see EXAMPLE bellow. +In this case there is no need to re-bind the notification +(it is assumed the socket is recycled) +This is critical for a real usage, as the re-bind operation is rather +expensive. + +.SH \ + +Subcommands: +.TP +.B new +Create a new notification. Conditions on matching jobs are specified +with exacltly one of +.B -j\fR, +.B -o\fR, +.B -n,\fR +.B -v +options. +Prints ID of the created notification. + +.TP +.B bind + +Binds to an existing notification, changing its listener eventually. +Useful for debugging purposes mostly. + +.TP +.B refresh + +Extend validity of an existing notification. + +.TP +.B receive + +Bind to an existing notification, and start waiting for an incoming +event, at most the time specified with +.B -i +(seconds). +.B -f +allows to specify a custom list of fields of the job status +to display. Run +.B glite-lb-notify +to get list of available fields. + +.TP +.B drop + +Drop the notification from the server, removing all messages on the way eventually. + +.SH EXAMPLE +Installed with the package as share/examples/glite-lb-notify.pl. +Demontstrates using the non-trivial +.B -s +option. + + +.SH SEE ALSO +.B glite-lb-bkserverd\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logd\fR(8) + +L&B Users Guide, http://www.glite.org + +.SH AUTHOR +EU EGEE JRA1, CESNET cluster. diff --git a/org.glite.lb.client/src/notify.c b/org.glite.lb.client/src/notify.c index 5d5ec2e..71b2b61 100644 --- a/org.glite.lb.client/src/notify.c +++ b/org.glite.lb.client/src/notify.c @@ -63,12 +63,16 @@ static void usage(char *cmd) if ( !cmd || !strcmp(cmd, "refresh") ) fprintf(stderr,"\n'refresh' command usage: %s refresh [-t requested_validity ] notifid\n" " notifid Notification ID.\n", me); - if ( !cmd || !strcmp(cmd, "receive") ) + if ( !cmd || !strcmp(cmd, "receive") ) { fprintf(stderr,"\n'receive' command usage: %s receive [ { -s socket_fd | -a fake_addr } ] [-t requested_validity ] [-i timeout] [-f field1,field2,...] [notifid]\n" " notifid Notification ID (not used if -s specified).\n" " fake_addr Fake the client address.\n" " field1,field2,... list of status fields to print (only owner by default)\n" " timeout Timeout to receive operation in seconds.\n", me); + fprintf(stderr,"\navailable fields:\n\t"); + dump_fields(); + putc(10,stderr); + } if ( !cmd || !strcmp(cmd, "drop") ) fprintf(stderr,"\n'drop' command usage: %s drop notifid\n" " notifid Notification to remove.\n", me); diff --git a/org.glite.lb.client/src/notify_supp.cpp b/org.glite.lb.client/src/notify_supp.cpp index 1b7bd61..05f3778 100644 --- a/org.glite.lb.client/src/notify_supp.cpp +++ b/org.glite.lb.client/src/notify_supp.cpp @@ -25,6 +25,7 @@ char * parse_fields(const char *arg,void **out) return NULL; } + std::string & escape(std::string &s) { for (std::string::iterator p = s.begin(); p < s.end(); p++) switch (*p) { @@ -39,6 +40,20 @@ std::string & escape(std::string &s) typedef std::vector > attrs_t; +void dump_fields(void) +{ + JobStatus s; + attrs_t a = s.getAttrs(); + for (attrs_t::iterator i=a.begin(); i != a.end(); i++) { + switch (i->second) { + case JobStatus::INT_T: + case JobStatus::STRING_T: + std::cerr << JobStatus::getAttrName(i->first) << ", "; + default: break; + } + } +} + void print_fields(void **ff,const edg_wll_NotifId n,edg_wll_JobStat const *s) { std::vector *fields = (std::vector *) ff; diff --git a/org.glite.lb.client/src/notify_supp.h b/org.glite.lb.client/src/notify_supp.h index 0d261d2..acb5322 100644 --- a/org.glite.lb.client/src/notify_supp.h +++ b/org.glite.lb.client/src/notify_supp.h @@ -4,6 +4,8 @@ extern "C" { char * parse_fields(const char *,void **); void print_fields(void **,const edg_wll_NotifId,edg_wll_JobStat const *); +void dump_fields(void); + #ifdef __cplusplus } -- 1.8.2.3