doc/man3: add flux_rpc(3), flux_rpc_the(3), etc.

Code examples are built as check_PROGRAMS and run as part of
sharness t/t0002-request.t

doc/man3/Makefile.am

@@ -11,7 +11,10 @@ MAN3_FILES_PRIMARY = \
 	flux_event_subscribe.3 \
 	flux_pollevents.3 \
 	flux_msg_encode.3 \
-	flux_msg_sendfd.3
+	flux_msg_sendfd.3 \
+	flux_rpc.3 \
+	flux_rpc_then.3 \
+	flux_rpc_multi.3
 
 # These files are generated as roff .so includes of a primary page.
 # A2X handles this automatically if mentioned in NAME section
@@ -25,7 +28,11 @@ MAN3_FILES_SECONDARY = \
 	flux_event_unsubscribe.3 \
 	flux_pollfd.3 \
 	flux_msg_decode.3 \
-	flux_msg_recvfd.3
+	flux_msg_recvfd.3 \
+	flux_rpc_destroy.3 \
+	flux_rpc_check.3 \
+	flux_rpc_get.3 \
+	flux_rpc_completed.3
 
 ADOC_FILES  = $(MAN3_FILES_PRIMARY:%.3=%.adoc)
 XML_FILES   = $(MAN3_FILES_PRIMARY:%.3=%.xml)
@@ -63,6 +70,10 @@ flux_event_unsubscribe.3: flux_event_subscribe.3
 flux_pollfd.3: flux_pollevents.3
 flux_msg_decode.3: flux_msg_encode.3
 flux_msg_recvfd.3: flux_msg_sendfd.3
+flux_rpc_destroy.3: flux_rpc.3
+flux_rpc_get.3: flux_rpc.3
+flux_rpc_check.3: flux_rpc_then.3
+flux_rpc_completed.3: flux_rpc_multi.3
 
 EXTRA_DIST = $(ADOC_FILES) COPYRIGHT.adoc
 
@@ -74,3 +85,21 @@ TESTS_ENVIRONMENT = \
 	man_dir=$(abs_srcdir)
 
 TESTS = spellcheck
+
+AM_CFLAGS = @GCCWARN@
+
+AM_CPPFLAGS = \
+        $(JSON_CFLAGS) $(ZMQ_CFLAGS) \
+        -I$(top_srcdir) -I$(top_srcdir)/src/include
+
+LDADD = \
+        $(top_builddir)/src/common/libflux-internal.la \
+        $(top_builddir)/src/common/libflux-core.la \
+        $(top_builddir)/src/common/libtap/libtap.la \
+        $(JSON_LIBS) $(ZMQ_LIBS) $(LIBPTHREAD)
+
+check_PROGRAMS = \
+	trpc \
+	trpc_then \
+	trpc_then_multi
+

doc/man3/flux_rpc.adoc

@@ -0,0 +1,134 @@
+flux_rpc(3)
+===========
+:doctype: manpage
+
+
+NAME
+----
+flux_rpc, flux_rpc_get, flux_rpc_destroy - perform a remote procedure call to a Flux service
+
+
+SYNOPSIS
+--------
+#include <flux/core.h>
+
+flux_rpc_t *flux_rpc (flux_t h, const char *topic, const char *json_str,
+                      uint32_t nodeid, int flags);
+
+void flux_rpc_destroy (flux_rpc_t *rpc);
+
+int flux_rpc_get (flux_rpc_t *rpc, uint32_t *nodeid, const char **json_str);
+
+
+DESCRIPTION
+-----------
+
+`flux_rpc()` constructs a request for the Flux service identified by
+_topic_, with optional payload _json_str_, that will routed be according
+to _nodeid_.  The request message is assigned a matchtag from the handle
+matchtag pool, and is then sent to the broker via handle _h_.
+A flux_rpc_t object is returned to the caller, used to complete the RPC.
+
+_nodeid_ affects how the broker will route the request, and may be set
+to one of the following values:
+
+FLUX_NODEID_ANY::
+Route to first available matching service instance.
+
+FLUX_NODEID_UPSTREAM::
+Route upstream via the tree based overlay network, then to first available
+matching service instance, skipping any instance on the sending rank.
+
+integer::
+Route to a specific broker rank.
+
+If _json_str_ is non-NULL, it must represent valid serialized JSON,
+and will be attached as request payload.
+
+Flags may be zero or a mask of the following values:
+
+FLUX_RPC_NORESPONSE::
+No response is expected, and the request will not be assigned a matchtag.
+The flux_rpc_t may be immediately destroyed.
+
+`flux_rpc_get()` obtains the result of the RPC, blocking until the response
+is received.  If non-NULL, _nodeid_ is set to the _nodeid_ argument given
+to `flux_rpc()` -- primarily useful with `flux_rpc_multi(3)`.  Similarly,
+_json_str_, if non-NULL, is set the response payload.  The storage associated
+with _json_str_ belongs to the flux_rpc_t object.  It is a protocol error
+if _json_str_ is NULL and the response has an unexpected payload, or if
+_json_str_ is non-NULL and the payload is missing.
+
+`flux_rpc_destroy()` destroys a completed `flux_rpc_t`, invalidating 
+any payload returned by `flux_rpc_get()`, and freeing matchtags.
+
+
+CANCELLATION
+------------
+
+Flux RFC 6 does not currently specify a cancellation protocol for an
+individual RPC, but does stipulate that an RPC may be canceled if a disconnect
+message is received, as is automatically generated by the local connector
+upon client disconnection.
+
+If `flux_rpc_destroy()` is called before a response is received, a
+matchtag value from the handle _h_'s matchtag pool is leaked.
+If enough matchtags are leaked, it will be impossible to make RPC calls
+on that handle.
+
+
+RETURN VALUE
+------------
+
+`flux_rpc()` returns a flux_rpc_t object on success.  On error, NULL
+is returned, and errno is set appropriately.
+
+`flux_rpc_get()` returns zero on success.  On error, -1 is returned,
+and errno is set appropriately.
+
+
+ERRORS
+------
+
+ENOSYS::
+Handle has no send operation.
+
+EINVAL::
+Some arguments were invalid.
+
+EPROTO::
+A protocol error was encountered.
+
+
+EXAMPLES
+--------
+
+This example performs a synchronous RPC with the broker's "cmb.info" service
+and extracts the broker's rank.
+
+....
+include::trpc.c[]
+....
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+---------
+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]

doc/man3/flux_rpc_multi.adoc

@@ -0,0 +1,116 @@
+flux_rpc_multi(3)
+=================
+:doctype: manpage
+
+
+NAME
+----
+flux_rpc_multi, flux_rpc_completed, - send a remote procedure call to a Flux service on multiple ranks
+
+
+SYNOPSIS
+--------
+#include <flux/core.h>
+
+flux_rpc_t *flux_rpc_multi (flux_t h, const char *topic, const char *json_str,
+                            const char *nodeset, int flags);
+
+bool flux_rpc_completed (flux_rpc_t *rpc);
+
+DESCRIPTION
+-----------
+
+`flux_rpc_multi()` sends requests to a Flux service identified by _topic_
+via Flux broker handle _h_.   The _nodeset_ represents a set of ranks
+that will receive the request, and is specified in bracketed range format,
+e.g. "[0-255]", "[1,3,5-10]", or "all" for all ranks in the session.
+
+If _json_str_ is non-NULL, it should represent a valid JSON string
+that will be attached as request payload.
+
+Flags may be zero or a mask of the following values:
+
+FLUX_RPC_NORESPONSE::
+No response will be expected to the request, and the request will not be
+assigned a matchtag.
+
+`flux_rpc_get(3)` may be used, as with `flux_rpc(3)`, to process responses.
+Each call to `flux_rpc_get(3)` invalidates any payload obtained via a
+previous call.
+
+`flux_rpc_check(3)` may be used, as with `flux_rpc(3)`, to determine
+whether `flux_rpc_get(3)` will block.
+
+`flux_rpc_completed()` returns true once all the RPC responses have been
+received and handled via `flux_rpc_get()`.  It can be used to terminate
+synchronous response collection, e.g.
+....
+while (!flux_rpc_completed (rpc))
+    flux_rpc_get (rpc, &nodeid, &payload);
+....
+
+`flux_rpc_then(3)` may be used, as with `flux_rpc(3)`, to register a
+reactor callback to handle each RPC responses message.
+
+`flux_rpc_destroy(3)` should be used to dispose of the flux_rpc_t object
+once the RPC has completed.  After this function is called, any payload
+returned by `flux_rpc_get()` is invalidated.
+
+
+RETURN VALUE
+------------
+
+`flux_rpc_multi()` returns a flux_rpc_t object on success.  On error, NULL
+is returned, and errno is set appropriately.
+
+`flux_rpc_completed()` returns true if the RPC has completed, else false.
+It does not report any errors.
+
+
+ERRORS
+------
+
+ENOSYS::
+Handle has no send operation.
+
+EINVAL::
+Some arguments were invalid.
+
+EPROTO::
+A protocol error was encountered.
+
+
+EXAMPLE
+-------
+
+This example performs an RPC with the broker's "cmb.info" service on all
+ranks.  A continuation is registered to process the responses as they arrive.
+The reactor loop terminates once the RPC is completed since the completion
+is its only event handler.
+
+....
+include::trpc_then_multi.c[]
+....
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+---------
+flux_rpc(3), flux_rpc_then(3)
+
+https://github.com/flux-framework/rfc/blob/master/spec_6.adoc[RFC 6: Flux
+Remote Procedure Call Protocol]