Skip to content

Latest commit

 

History

History
124 lines (82 loc) · 3.24 KB

flux_rpc_raw.adoc

File metadata and controls

124 lines (82 loc) · 3.24 KB
Raw

flux_rpc_raw(3) Manual Page

NAME

flux_rpc_raw, flux_rpc_get_raw - perform a remote procedure call to a Flux service using raw payloads

SYNOPSIS

#include <flux/core.h>
flux_rpc_t *flux_rpc_raw (flux_t *h, const char *topic,
                          const void *data_in, int length_in,
                          uint32_t nodeid_in, int flags);
int flux_rpc_get_raw (flux_rpc_t *rpc, uint32_t *nodeid_out,
                      void *data_out, int *length_out);

DESCRIPTION

flux_rpc_raw() encodes and sends a request message, comprising the first half of a remote procedure call (RPC). A flux_rpc_t object is returned which can be passed to flux_rpc_get_raw() to obtain the decoded response message, comprising the second half of the RPC. The flux_rpc_t should finally be disposed of using flux_rpc_destroy().

The raw RPC functions may be paired with the JSON RPC functions flux_rpc(3) and flux_rpc_get(3). That is, it is valid to send a JSON request payload and receive a raw response payload, or the reverse.

topic must be set to a topic string representing the Flux service that will handle the request.

data_in, if non-NULL, points to a payload of size length_in. If NULL, the request will be sent without a payload.

nodeid_in affects request routing, and must be set to one of the following values:

FLUX_NODEID_ANY

The request is routed to the first matching service instance.

FLUX_NODEID_UPSTREAM

The request is routed to the first matching service instance, skipping over the sending rank.

integer

The request is routed to a specific rank.

flags may be zero or:

FLUX_RPC_NORESPONSE

No response is expected. The request will not be assigned a matchtag, and the flux_rpc_t returned by flux_rpc() may be immediately destroyed.

flux_rpc_get_raw() blocks until a matching response is received, then decodes the result. For asynchronous response handling, see flux_rpc_then(3).

data_out and length_out, which must be non-NULL, are assigned a pointer to the response payload and its length. If there is no response payload, they will be sent to NULL and zero, respectively. Any storage associated with data_out belongs to the flux_rpc_t object and is invalidated when that object is destroyed.

nodeid_out, if non-NULL, is set to the nodeid_in argument given to flux_rpc_raw(). This is primarily useful with flux_rpc_multi(3).

RETURN VALUE

flux_rpc_raw() returns a flux_rpc_t object on success. On error, NULL is returned, and errno is set appropriately.

flux_rpc_get_raw() 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.

CAVEATS

Although flux_rpc_get_raw() can be used with flux_rpc_multi(), there is no flux_rpc_multi_raw().

AUTHOR

This page is maintained by the Flux community.

COPYRIGHT

SEE ALSO

flux_rpc(3), flux_rpc_then(3), flux_rpc_multi(3)