kinetic-c  v0.12.0
Seagate Kinetic Protocol Client Library for C
bus_types.h
Go to the documentation of this file.
1 /*
2 * kinetic-c
3 * Copyright (C) 2015 Seagate Technology.
4 *
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License
7 * as published by the Free Software Foundation; either version 2
8 * of the License, or (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 *
19 */
20 #ifndef BUS_TYPES_H
21 #define BUS_TYPES_H
22 
23 #include <stdbool.h>
24 #include <stdint.h>
25 
26 #include "threadpool.h"
27 
28 /* Boxed type for the internal state used while asynchronously
29  * processing an message. */
30 struct boxed_msg;
31 
32 /* Max number of concurrent sends that can be active. */
33 #define BUS_MAX_CONCURRENT_SENDS 10
34 
35 /* Default number of seconds before a message response times out. */
36 #define BUS_DEFAULT_TIMEOUT_SEC 10
37 
38 /* Special sequence ID value indicating none was available. */
39 #define BUS_NO_SEQ_ID (-1)
40 
41 #ifdef TEST
42 #define BUS_LOG(B, LEVEL, EVENT_KEY, MSG, UDATA) (void)B
43 #define BUS_LOG_SNPRINTF(B, LEVEL, EVENT_KEY, UDATA, MAX_SZ, FMT, ...) (void)B
44 #else
45 #define BUS_LOG(B, LEVEL, EVENT_KEY, MSG, UDATA) \
46  do { \
47  struct bus *_b = (B); \
48  int _level = LEVEL; \
49  log_event_t _event_key = EVENT_KEY; \
50  char *_msg = MSG; \
51  void *_udata = UDATA; \
52  if (_b->log_level >= _level && _b->log_cb != NULL) { \
53  _b->log_cb(_event_key, _level, _msg, _udata); \
54  } \
55  } while (0)
56 
57 #define BUS_LOG_STRINGIFY(X) #X
58 
59 #define BUS_LOG_SNPRINTF(B, LEVEL, EVENT_KEY, UDATA, MAX_SZ, FMT, ...) \
60  do { \
61  struct bus *_b = (B); \
62  int _level = LEVEL; \
63  log_event_t _event_key = EVENT_KEY; \
64  void *_udata = UDATA; \
65  if (_b->log_level >= _level && _b->log_cb != NULL) { \
66  char _log_buf[MAX_SZ]; \
67  if (MAX_SZ < snprintf(_log_buf, MAX_SZ, \
68  FMT, __VA_ARGS__)) { \
69  _b->log_cb(_event_key, _level, \
70  "snprintf failure -- " \
71  __FILE__, \
72  _udata); \
73  char _line_buf[32]; \
74  snprintf(_line_buf, 32, "line %d\n", __LINE__); \
75  _b->log_cb(_event_key, _level, _line_buf, _udata); \
76  } else { \
77  _b->log_cb(_event_key, _level, _log_buf, _udata); \
78  } \
79  } \
80  } while (0)
81 #endif
82 
83 #define BUS_ASSERT(B, UDATA, COND) \
84  do { \
85  if(!(COND)) \
86  { \
87  BUS_LOG_SNPRINTF(B, 0, LOG_ASSERT, UDATA, 128, \
88  "BUS FAILURE at %s:%d in %s: assert(" #COND ")", \
89  __FILE__, (int)__LINE__, __func__); \
90  assert(COND); \
91  } \
92  } while(0)
93 
94 /* Event tag for a log message. */
95 typedef enum {
105  /* ... */
107 } log_event_t;
108 
109 /* Pass an event to log. */
110 typedef void (bus_log_cb)(log_event_t event, int log_level, const char *msg, void *udata);
111 
112 /* Result from bus_sink_cb. See below. */
113 typedef struct {
114  size_t next_read; /* size for next read */
115  void *full_msg_buffer; /* can be NULL */
117 
118 /* Sink READ_SIZE bytes in READ_BUF into a protocol handler. This read
119  * size is based on the previously requested size. (If the size for the
120  * next request is undefined, this can be called with a READ_SIZE of 0.)
121  *
122  * The (void *) that was passed in during Bus_RegisterSocket will be
123  * passed along.
124  *
125  * A bus_sink_cb_res_t struct should be returned, with next_read
126  * indicating that the callback should be called again once NEXT_READ
127  * bytes are available (more may be buffered internally). If
128  * FULL_MSG_BUFFER is non-NULL, then that buffer will be passed to
129  * BUS_UNPACK_CB (below) for further processing. */
131  size_t read_size, void *socket_udata);
132 
133 /* Result from an attempting to unpack a message according to the user
134  * protocol's unpack callback. See bus_unpack_cb below. */
135 typedef struct {
136  bool ok; /* could be a type tag */
137  union {
138  struct {
139  void *msg; /* protocol message to sink to CB */
140  int64_t seq_id; /* sequence ID for message */
141  } success;
142  struct {
143  uintptr_t opaque_error_id;
144  } error;
145  } u;
147 
148 /* Unpack a message that has been gradually accumulated via bus_sink_cb.
149  *
150  * Note that the udata pointer is socket-specific, NOT client-specific. */
151 typedef bus_unpack_cb_res_t (bus_unpack_cb)(void *msg, void *socket_udata);
152 
153 /* Handle a result from bus_unpack_cb that is marked as an error. */
154 typedef void (bus_error_cb)(bus_unpack_cb_res_t result, void *socket_udata);
155 
156 /* Process a message that was successfully unpacked, but does not have
157  * an expected sequence ID. This is likely a keepalive message, status
158  * message, etc. */
159 typedef void (bus_unexpected_msg_cb)(void *msg,
160  int64_t seq_id, void *bus_udata, void *socket_udata);
161 
162 /* Configuration for the messaging bus */
163 typedef struct bus_config {
164  /* If omitted, these fields will be set to defaults. */
167 
168  /* Callbacks */
169  bus_sink_cb *sink_cb; /* required */
170  bus_unpack_cb *unpack_cb; /* required */
173 
175  bus_log_cb *log_cb; /* optional */
176 
177  void *bus_udata;
178 } bus_config;
179 
180 typedef enum {
192 
193 typedef enum {
198  BUS_SEND_TX_FAILURE = -52, // -> socket error
207 
208 /* Result from attempting to configure a message bus. */
209 typedef struct bus_result {
211  struct bus *bus;
212 } bus_result;
213 
214 /* Callback for a request's result. */
215 typedef struct {
216  bus_send_status_t status; // request_status
217  union {
218  struct {
219  const char *err_str;
220  } error_minutiae;
221  struct {
222  // user needs to free *msg
223  int64_t seq_id;
224  void *opaque_msg;
225  } response;
226  } u;
228 
229 typedef void (bus_msg_cb)(bus_msg_result_t *res, void *udata);
230 
231 typedef enum {
234 } bus_socket_t;
235 
236 /* A message being packaged for delivery by the message bus. */
237 typedef struct {
238  int fd;
240  int64_t seq_id;
241  uint8_t *msg;
242  size_t msg_size;
243  uint16_t timeout_sec;
244 
246  void *udata;
247 } bus_user_msg;
248 
249 /* This opaque bus struct represents the only user-facing interface to
250  * the network handling code. Callbacks are provided to react to network
251  * events. */
252 struct bus_t;
253 
254 typedef enum {
255  /* Message successfully processed. */
257 
258  /* Tried te send a request, timed out */
260 
261  /* Tried to send a request, remote end hung up */
263 
264  /* Timeout while waiting for response */
266 
267  /* Remote end hung up while waiting for response */
270 
271 #endif
Bus_Init_res_t status
Definition: bus_types.h:210
size_t msg_size
Definition: bus_types.h:242
void * opaque_msg
Definition: bus_types.h:224
bus_sink_cb_res_t( bus_sink_cb)(uint8_t *read_buf, size_t read_size, void *socket_udata)
Definition: bus_types.h:130
log_event_t
Definition: bus_types.h:95
bus_socket_t type
Definition: bus_types.h:239
bus_unpack_cb * unpack_cb
Definition: bus_types.h:170
Configuration for thread pool.
Definition: threadpool.h:34
void * bus_udata
Definition: bus_types.h:177
const char * err_str
Definition: bus_types.h:219
static uint8_t read_buf[(2 *1024L *1024)]
Definition: echosrv.c:44
int listener_count
Definition: bus_types.h:165
Message bus.
bus_unpack_cb_res_t( bus_unpack_cb)(void *msg, void *socket_udata)
Definition: bus_types.h:151
bus_unexpected_msg_cb * unexpected_msg_cb
Definition: bus_types.h:171
uintptr_t opaque_error_id
Definition: bus_types.h:143
void * udata
Definition: bus_types.h:246
struct threadpool_config threadpool_cfg
Definition: bus_types.h:166
bus_msg_cb * cb
Definition: bus_types.h:245
bus_send_status_t status
Definition: bus_types.h:216
void( bus_msg_cb)(bus_msg_result_t *res, void *udata)
Definition: bus_types.h:229
bus_error_cb * error_cb
Definition: bus_types.h:172
bus_socket_t
Definition: bus_types.h:231
bus_send_status_t
Definition: bus_types.h:193
int log_level
Definition: bus_types.h:174
uint16_t timeout_sec
Definition: bus_types.h:243
void( bus_log_cb)(log_event_t event, int log_level, const char *msg, void *udata)
Definition: bus_types.h:110
Bus_Init_res_t
Definition: bus_types.h:180
bus_sink_cb * sink_cb
Definition: bus_types.h:169
void * full_msg_buffer
Definition: bus_types.h:115
int64_t seq_id
Definition: bus_types.h:223
struct bus * bus
Definition: bus_types.h:211
bus_log_cb * log_cb
Definition: bus_types.h:175
void( bus_unexpected_msg_cb)(void *msg, int64_t seq_id, void *bus_udata, void *socket_udata)
Definition: bus_types.h:159
uint8_t * msg
Definition: bus_types.h:241
bus_status_res_t
Definition: bus_types.h:254
void( bus_error_cb)(bus_unpack_cb_res_t result, void *socket_udata)
Definition: bus_types.h:154
int64_t seq_id
Definition: bus_types.h:240