Merge pull request #857 from garlick/flux_msg_t

make flux_msg_t a bonafide type, add jansson payload accessors

doc/man1/flux-snoop.adoc

@@ -66,10 +66,6 @@ OPTIONS
 *-a, --all*::
 Do not suppress 'cmb.info', 'cmb.log', and 'cmb.pub' messages.
 
-*-l, --long*::
-Display long format of message dumps.  Do not truncate at 80 columns.
-Do not compress DEALER - ROUTER routing frames into a single line.
-
 AUTHOR
 ------
 This page is maintained by the Flux community.

doc/man3/Makefile.am

@@ -35,7 +35,9 @@ MAN3_FILES_PRIMARY = \
 	flux_stat_watcher_create.3 \
 	flux_rpc_raw.3 \
 	flux_respond.3 \
-	flux_reactor_now.3
+	flux_reactor_now.3 \
+	flux_request_decode.3 \
+	flux_event_decode.3
 
 # These files are generated as roff .so includes of a primary page.
 # A2X handles this automatically if mentioned in NAME section
@@ -91,7 +93,13 @@ MAN3_FILES_SECONDARY = \
 	flux_stat_watcher_get_rstat.3 \
 	flux_rpc_get_raw.3 \
 	flux_respond_raw.3 \
-	flux_reactor_now_update.3
+	flux_respondf.3 \
+	flux_reactor_now_update.3 \
+	flux_request_decodef.3 \
+	flux_request_decode_raw.3 \
+	flux_event_decodef.3 \
+	flux_event_encode.3 \
+	flux_event_encodef.3
 
 ADOC_FILES  = $(MAN3_FILES_PRIMARY:%.3=%.adoc)
 XML_FILES   = $(MAN3_FILES_PRIMARY:%.3=%.xml)
@@ -165,7 +173,13 @@ flux_child_watcher_get_rstatus.3: flux_child_watcher_create.3
 flux_stat_watcher_get_rstat.3: flux_stat_watcher_create.3
 flux_rpc_get_raw.3: flux_rpc_raw.3
 flux_respond_raw.3: flux_respond.3
+flux_respondf.3: flux_respond.3
 flux_reactor_now_update.3: flux_reactor_now.3
+flux_request_decodef.3: flux_request_decode.3
+flux_request_decode_raw.3: flux_request_decode.3
+flux_event_decodef.3: flux_event_decode.3
+flux_event_encode.3: flux_event_decode.3
+flux_event_encodef.3: flux_event_decode.3
 
 flux_open.3: topen.c
 flux_send.3: tsend.c

doc/man3/flux_event_decode.adoc

@@ -0,0 +1,108 @@
+flux_event_decode(3)
+====================
+:doctype: manpage
+
+
+NAME
+----
+flux_event_decode, flux_event_decodef, flux_event_encode, flux_event_encodef 
+ - encode/decode a Flux event message
+
+
+SYNOPSIS
+--------
+ #include <flux/core.h>
+
+ int flux_event_decode (const flux_msg_t *msg,
+                        const char **topic,
+                        const char **json_str);
+
+ int flux_event_decodef (const flux_msg_t *msg,
+                         const char **topic,
+                         const char *fmt, ...);
+
+ flux_msg_t *flux_event_encode (const char *topic,
+                                const char *json_str);
+
+ flux_msg_t *flux_event_encodef (const char *topic,
+                                 const char *fmt, ...);
+
+
+DESCRIPTION
+-----------
+
+`flux_event_decode()` decodes a Flux event message _msg_.
+
+_topic_, if non-NULL, will be set the message's topic string. The storage
+for this string belongs to _msg_ and should not be freed.
+
+_json_str_, if non-NULL, will be set to the message's JSON payload. The
+storage for this string belongs to _msg_ and should not be freed.
+If non-NULL, decoding fails if the message doesn't have a JSON payload.
+If NULL, decoding fails if the message does have a JSON payload.
+
+`flux_event_decodef()` decodes a Flux event message with a JSON payload as
+above, parsing the payload using variable arguments with a format string
+in the style of jansson's `json_unpack()` (used internally). Decoding fails
+if the message doesn't have a JSON payload.
+
+`flux_event_encode()` encodes a Flux event message with topic string _topic_
+and optional JSON payload _json_str_.  The newly constructed message that
+is returned must be destroyed with `flux_msg_destroy()`.
+
+`flux_event_decodef()` decodes a Flux event message with a JSON payload as
+above, parsing the payload using variable arguments with a format string
+in the style of jansson's `json_unpack()` (used internally). Decoding fails
+if the message doesn't have a JSON payload.
+
+Events propagated to all subscribers.  Events will not be received
+without a matching subscription established using `flux_event_subscribe()`.
+
+
+RETURN VALUE
+------------
+
+Decoding functions return 0 on success.  On error, -1 is returned, and
+errno is set appropriately.
+
+Encoding functions return a message on success.  On error, NULL is returned,
+and errno is set appropriately.
+
+
+ERRORS
+------
+
+EINVAL::
+The _msg_ argument was NULL or there was a problem encoding.
+
+ENOMEM::
+Memory was unavailable.
+
+EPROTO::
+Message decoding failed, such as due to missing or unexpected payload,
+incorrect message type, missing topic string, etc..
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+---------
+flux_event_subscribe(3)
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#parsing-and-validating-values[Jansson API: Parsing and Validating Values]
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#building-values[Jansson API: Building Values]
+

doc/man3/flux_request_decode.adoc

@@ -0,0 +1,87 @@
+flux_request_decode(3)
+======================
+:doctype: manpage
+
+
+NAME
+----
+flux_request_decode, flux_request_decodef, flux_request_decode_raw - decode a Flux request message
+
+
+SYNOPSIS
+--------
+ #include <flux/core.h>
+
+ int flux_request_decode (const flux_msg_t *msg,
+                          const char **topic,
+                          const char **json_str);
+
+ int flux_request_decodef (const flux_msg_t *msg,
+                           const char **topic,
+                           const char *fmt, ...);
+
+ int flux_request_decode_raw (const flux_msg_t *msg,
+                              const char **topic,
+                              void *data, int *len);
+
+DESCRIPTION
+-----------
+
+`flux_request_decode()` decodes a request message _msg_.
+
+_topic_, if non-NULL, will be set the message's topic string. The storage
+for this string belongs to _msg_ and should not be freed.
+
+_json_str_, if non-NULL, will be set to the message's JSON payload. The
+storage for this string belongs to _msg_ and should not be freed.
+If non-NULL, decoding fails if the message doesn't have a JSON payload.
+If NULL, decoding fails if the message does have a JSON payload.
+
+`flux_request_decodef()` decodes a request message with a JSON payload as
+above, parsing the payload using variable arguments with a format string
+in the style of jansson's `json_unpack()` (used internally). Decoding fails
+if the message doesn't have a JSON payload.
+
+`flux_request_decode_raw()` decodes a request message with a raw payload,
+setting _data_ and _len_ to the payload data and length. The storage for
+the raw payload belongs to _msg_ and should not be freed.
+
+
+RETURN VALUE
+------------
+
+These functions return 0 on success.  On error, -1 is returned, and
+errno is set appropriately.
+
+
+ERRORS
+------
+
+EINVAL::
+The _msg_ argument was NULL.
+
+EPROTO::
+Message decoding failed, such as due to missing or unexpected payload,
+incorrect message type, missing topic string, etc..
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+---------
+flux_respond(3), flux_rpc(3)
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#parsing-and-validating-values[Jansson API: Parsing and Validating Values]

doc/man3/flux_respond.adoc

@@ -5,7 +5,7 @@ flux_respond(3)
 
 NAME
 ----
-flux_respond, flux_respond_raw - respond to a request
+flux_respond, flux_respondf, flux_respond_raw - respond to a request
 
 
 SYNOPSIS
@@ -15,15 +15,19 @@ SYNOPSIS
  int flux_respond (flux_t *h, const flux_msg_t *request,
                    int errnum, const char *json_str);
 
+ int flux_respondf (flux_t *h, const flux_msg_t *request,
+                    const char *fmt, ...);
+
  int flux_respond_raw (flux_t *h, const flux_msg_t *request,
                        int errnum, const void *data, int length);
 
+
 DESCRIPTION
 -----------
 
-`flux_respond()` and `flux_respond_raw()` encode and send a response
-message on handle _h_, deriving topic string, matchtag, and route stack
-from the provided _request_.
+`flux_respond()`, `flux_respondf()`, and `flux_respond_raw()` encode
+and send a response message on handle _h_, deriving topic string,
+matchtag, and route stack from the provided _request_.
 
 If _errnum_ is non-zero, an error is returned to the sender such that
 `flux_rpc_get(3)` or `flux_rpc_get_raw(3)` will fail, with the system
@@ -33,6 +37,10 @@ If _json_str_ is non-NULL, `flux_respond()` will send it as the response
 payload, otherwise there will be no payload.  Similarly, if _data_ is
 non-NULL, `flux_respond_raw()` will send it as the response payload.
 
+`flux_respondf()` encodes a response message with a JSON payload,
+building the payload using variable arguments with a format string in
+the style of jansson's `json_pack()` (used internally).
+
 
 RETURN VALUE
 ------------
@@ -77,3 +85,5 @@ https://github.com/flux-framework/rfc/blob/master/spec_6.adoc[RFC 6: Flux
 Remote Procedure Call Protocol]
 
 https://github.com/flux-framework/rfc/blob/master/spec_3.adoc[RFC 3: CMB1 - Flux Comms Message Broker Protocol]
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#building-values[Jansson API: Building Values]

doc/man3/flux_rpc.adoc

@@ -80,14 +80,14 @@ an RPC before completion renders the matchtag associated with the RPC
 unusable; it is effectively leaked from the matchtag pool.
 
 `flux_rpcf()` is a variant of `flux_rpc()` that constructs a JSON
-payload based on the provided `fmt` string and variable arguments.
-The `fmt` string and variable arguments are passed internally to
+payload based on the provided _fmt_ string and variable arguments.
+The _fmt_ string and variable arguments are passed internally to
 jansson's `json_pack()` function.  See jansson documentation for
 details.
 
 `flux_rpc_getf()` is a variant of `flux_rpc_get()` that parses a JSON
-payload based on the provided `fmt` string and variable arguments.
-The `fmt` string and variable arguments are passed internally to
+payload based on the provided _fmt_ string and variable arguments.
+The _fmt_ string and variable arguments are passed internally to
 jansson's `json_unpack()` function.  Any strings or objects returned
 are invalidated when `flux_rpc_destroy()` is called.  See jansson
 documentation for details.
@@ -162,3 +162,7 @@ flux_rpc_then(3), flux_rpc_multi(3)
 
 https://github.com/flux-framework/rfc/blob/master/spec_6.adoc[RFC 6: Flux
 Remote Procedure Call Protocol]
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#parsing-and-validating-values[Jansson API: Parsing and Validating Values]
+
+http://jansson.readthedocs.io/en/2.7/apiref.html#building-values[Jansson API: Building Values]

doc/test/spell.en.pws

@@ -334,3 +334,7 @@ getf
 jansson
 jansson's
 rpcf
+decodef
+len
+respondf
+encodef