Merge 16093e7 into 54ce1fb

doc/man1/flux-kvs.adoc

@@ -167,6 +167,20 @@ display the namespace owner.  If '-s' is specified, display the root
 sequence number.  If '-w' is specified, display the current root,
 then a new value each time it is updated, up to 'count', if specified.
 
+*eventlog get* [-w] [-c count] [-u] 'key'::
+Display the contents of an RFC 18 KVS eventlog referred to by 'key'.
+If '-u' is specified, display the log in raw form, otherwise format the
+dates as ISO 8601.  If '-w' is specified, after the existing contents
+have been displayed, the eventlog is monitored and updates are
+displayed as they are committed.  This runs until the program is
+interrupted or an error occurs, unless the number of events is limited
+with the '-c' option.
+
+*eventlog append* [-t SECONDS] 'key' 'name' ['context ...']::
+Append an event to an RFC 18 KVS eventlog referred to by 'key'.
+The event 'name' and optional 'context' are specified on the command line.
+The timestamp may optionally be specified with '-t' as decimal seconds since
+the UNIX epoch (UTC), otherwise the current wall clock is used.
 
 AUTHOR
 ------

doc/man3/Makefile.am

@@ -52,6 +52,7 @@ MAN3_FILES_PRIMARY = \
 	flux_kvs_namespace_list.3 \
 	flux_kvs_set_namespace.3 \
 	flux_kvs_getroot.3 \
+	flux_kvs_eventlog_create.3 \
 	idset_create.3
 
 # These files are generated as roff .so includes of a primary page.
@@ -177,6 +178,13 @@ MAN3_FILES_SECONDARY = \
 	flux_kvs_namespace_itr_rewind.3 \
 	flux_kvs_namespace_itr_destroy.3 \
 	flux_kvs_get_namespace.3 \
+	flux_kvs_eventlog_destroy.3 \
+	flux_kvs_eventlog_encode.3 \
+	flux_kvs_eventlog_decode.3 \
+	flux_kvs_eventlog_update.3 \
+	flux_kvs_eventlog_append.3 \
+	flux_kvs_eventlog_first.3 \
+	flux_kvs_eventlog_next.3 \
 	idset_destroy.3 \
 	idset_encode.3 \
 	idset_decode.3
@@ -322,6 +330,13 @@ flux_kvs_namespace_itr_next.3: flux_kvs_namespace_list.3
 flux_kvs_namespace_itr_rewind.3: flux_kvs_namespace_list.3
 flux_kvs_namespace_itr_destroy.3: flux_kvs_namespace_list.3
 flux_kvs_get_namespace.3: flux_kvs_set_namespace.3
+flux_kvs_eventlog_destroy.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_encode.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_decode.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_update.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_append.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_first.3: flux_kvs_eventlog_create.3
+flux_kvs_eventlog_next.3: flux_kvs_eventlog_create.3
 idset_destroy.3: idset_create.3
 idset_encode.3: idset_create.3
 idset_decode.3: idset_create.3

doc/man3/flux_kvs_eventlog_create.adoc

@@ -0,0 +1,139 @@
+flux_kvs_eventlog_create(3)
+===========================
+:doctype: manpage
+
+
+NAME
+----
+flux_kvs_eventlog_create, flux_kvs_eventlog_destroy, flux_kvs_eventlog_encode, flux_kvs_eventlog_decode, flux_kvs_eventlog_update, flux_kvs_eventlog_append, flux_kvs_eventlog_first, flux_kvs_eventlog_next - manipulate RFC 18 KVS eventlogs
+
+
+SYNOPSIS
+--------
+
+ struct flux_kvs_eventlog *flux_kvs_eventlog_create (void);
+
+ void flux_kvs_eventlog_destroy (struct flux_kvs_eventlog *eventlog);
+
+ char *flux_kvs_eventlog_encode (const struct flux_kvs_eventlog *eventlog);
+
+ struct flux_kvs_eventlog *flux_kvs_eventlog_decode (const char *s);
+
+ int flux_kvs_eventlog_update (struct flux_kvs_eventlog *eventlog,
+                               const char *s);
+
+ int flux_kvs_eventlog_append (struct flux_kvs_eventlog *eventlog,
+                               const char *s);
+
+ const char *flux_kvs_eventlog_first (struct flux_kvs_eventlog *eventlog);
+
+ const char *flux_kvs_eventlog_next (struct flux_kvs_eventlog *eventlog);
+
+ int flux_kvs_event_decode (const char *s,
+                            double *timestamp,
+                            flux_kvs_event_name_t name,
+                            flux_kvs_event_context_t context);
+
+ char *flux_kvs_event_encode (const char *name, const char *context);
+
+ char *flux_kvs_event_encode_timestamp (double timestamp,
+                                       const char *name,
+                                       const char *context);
+
+
+
+DESCRIPTION
+-----------
+
+An RFC 18 KVS eventlog consists of single line log entries of the form:
+
+  timestamp name [context ...]\n
+
+Where 'timestamp' is seconds since the UNIX epoch (UTC), in decimal form;
+'name' is a 64 character or less event name, and 'context' is an optional
+256 character or less free form string.  Each event is terminated by a newline
+character.
+
+Raw event strings can be atomically appended to an eventlog stored in the KVS
+using `flux_kvs_txn_put()` with the the 'FLUX_KVS_APPEND' flag.
+The eventlog can be accessed with `flux_kvs_lookup()`, optionally with
+the 'FLUX_KVS_WATCH' flag.
+
+`flux_kvs_eventlog_create()` creates an empty eventlog object in memory,
+and `flux_kvs_eventlog_destroy()` disposes of it.
+
+`flux_kvs_eventlog_decode()` creates an eventlog object from raw RFC 18
+eventlog data in string form, such as would be returned by
+`flux_kvs_lookup_get()`.  The caller must free the returned object.
+`flux_kvs_eventlog_encode()` performs the opposite function; again, the
+caller must free the returned string.
+
+`flux_kvs_eventlog_update()` updates an eventlog object with a new snapshot
+of the raw log, such as might be returned from `flux_kvs_lookup_get()`.
+This function does not change the iterator cursor.
+
+`flux_kvs_eventlog_append()` appends a single raw event to the eventlog.
+
+The events in an eventlog object may be accessed in raw form  with the
+iterators `flux_kvs_eventlog_first()` and `flux_kvs_eventlog_next()`.
+These functions return NULL when the end of the log has been reached.
+Pointers returned by these functions remain valid until the object
+is destroyed.
+
+`flux_kvs_event_decode()` decodes a raw event, copying the timestamp,
+name, and context fields to the supplied storage.  A field may be
+ignored by setting the corresponding parameter to zero.  If the optional
+context is not present, the supplied storage will be filled with the
+empty string.
+
+`flux_kvs_event_encode()` creates a raw event from the supplied fields.
+The timestamp is assigned the current wallclock time. The caller must
+free the returned event string.  `flux_kvs_event_encode_timestamp()` is
+the same except the timestamp value may be explicitly set.
+
+RETURN VALUE
+------------
+
+`flux_kvs_eventlog_create()` and `flux_kvs_eventlog_decode()` return
+an eventlog object on success, or NULL on failure with errno set.
+
+`flux_kvs_eventlog_encode()`, `flux_kvs_event_encode()`, and
+`flux_kvs_event_encode_timestamp()` return encoded strings on success,
+or NULL on failure with errno set.
+
+`flux_kvs_eventlog_update()`, `flux_kvs_eventlog_append()`, and
+`flux_kvs_event_decode()` return 0 on success, or -1 on failure
+with errno set.
+
+`flux_kvs_eventlog_first()` and `flux_kvs_eventlog_next()` return
+a const pointer to a raw event, or NULL if the internal cursor has
+reached the end of the log.
+
+ERRORS
+------
+
+EINVAL::
+One of the arguments was invalid.
+
+ENOMEM::
+Out of memory.
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+---------
+flux_kvs_lookup (3), flux_kvs_txn_create (3)

doc/test/spell.en.pws

@@ -444,3 +444,5 @@ gpus
 fulfillments
 enodata
 getroot
+eventlog
+eventlogs