grpc_channel.h

Go to the documentation of this file.

 
#ifndef __CWIST_GRPC_CHANNEL_H__
#define __CWIST_GRPC_CHANNEL_H__
 
#include <cwist/net/grpc/grpc_client.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct cwist_grpc_channel cwist_grpc_channel;
typedef struct cwist_grpc_channel_call cwist_grpc_channel_call;
 
typedef enum cwist_grpc_lb_policy {
    CWIST_GRPC_LB_PICK_FIRST = 0,   /* default (doc/load-balancing.md) */
    CWIST_GRPC_LB_ROUND_ROBIN = 1,
} cwist_grpc_lb_policy;
 
typedef enum cwist_grpc_channel_state {
    CWIST_GRPC_CHANNEL_IDLE = 0,
    CWIST_GRPC_CHANNEL_CONNECTING,
    CWIST_GRPC_CHANNEL_READY,
    CWIST_GRPC_CHANNEL_TRANSIENT_FAILURE,
    CWIST_GRPC_CHANNEL_SHUTDOWN,
} cwist_grpc_channel_state;
 
#define CWIST_GRPC_STATUS_BIT(code) (1u << (code))
 
typedef struct cwist_grpc_retry_policy {
    uint32_t max_attempts;         /* RPC attempts incl. the original; >= 2,
                            * clamped to the client-side maximum of 5 */
    uint64_t initial_backoff_ms;   /* > 0; first retry after
                                  * initial_backoff * random(0.8, 1.2) */
    uint64_t max_backoff_ms;       /* > 0 */
    double backoff_multiplier;     /* > 0; nth retry waits
                                * min(initial*mult^(n-1), max) * random(0.8,1.2) */
    uint32_t retryable_status_mask; /* CWIST_GRPC_STATUS_BIT() per retryable code */
} cwist_grpc_retry_policy;
 
typedef struct cwist_grpc_retry_throttle {
    double max_tokens;   /* (0, 1000]; token_count starts here */
    double token_ratio;  /* > 0; added to token_count per successful RPC */
} cwist_grpc_retry_throttle;
 
typedef struct cwist_grpc_channel_options {
    const char *authority;        /* :authority header; defaults to the target host:port */
    int use_tls;                  /* 0 = h2c cleartext, 1 = TLS (ALPN "h2") */
    int verify_peer;              /* TLS only: verify server certificate (default 1) */
    uint64_t connect_timeout_ms;  /* 0 = 10000 */
    cwist_grpc_lb_policy lb_policy;                      /* default pick_first */
    const cwist_grpc_retry_policy *retry_policy; /* NULL = retries disabled (A6 default) */
    const cwist_grpc_retry_throttle *retry_throttle; /* NULL = no throttling */
    uint64_t per_rpc_buffer_limit; /* 0 = 256 KiB; requests larger than this
                                    * are sent but never retried (A6 buffering) */
    int wait_for_ready; /* 0 = fail fast UNAVAILABLE while no
                         * subchannel is READY; 1 = wait until the
                         * call deadline */
} cwist_grpc_channel_options;
 
cwist_grpc_channel *cwist_grpc_channel_connect(const char *target,
                                               const cwist_grpc_channel_options *options);
 
void cwist_grpc_channel_close(cwist_grpc_channel *channel);
 
cwist_grpc_channel_state cwist_grpc_channel_get_state(cwist_grpc_channel *channel);
 
int cwist_grpc_channel_apply_service_config_json(cwist_grpc_channel *channel, const char *json);
 
cwist_grpc_channel_call *cwist_grpc_channel_call_start(cwist_grpc_channel *channel,
                                                       const char *method, const void *request,
                                                       size_t request_len, uint64_t timeout_ms);
 
int cwist_grpc_channel_call_recv(cwist_grpc_channel_call *call, cwist_grpc_message *out);
cwist_grpc_status_t cwist_grpc_channel_call_finish(cwist_grpc_channel_call *call,
                                                   const char **message);
void cwist_grpc_channel_call_cancel(cwist_grpc_channel_call *call);
void cwist_grpc_channel_call_destroy(cwist_grpc_channel_call *call);
 
uint32_t cwist_grpc_channel_call_attempts(const cwist_grpc_channel_call *call);
 
cwist_grpc_status_t cwist_grpc_channel_unary(cwist_grpc_channel *channel, const char *method,
                                             const void *request, size_t request_len,
                                             uint64_t timeout_ms, uint8_t **response,
                                             size_t *response_len, char **status_message);
 
#ifdef __cplusplus
}
#endif
 
#endif