api: add new stream message convention

Instead of having to wrap dump/detail calls in control ping, send details messages in between a normal
reply / request pair. As expressed in the below service statement.

Example:

service {
  rpc map_domains_gets returns map_domains_get_reply
    stream map_domain_details;
};

define map_domains_get
{
  u32 client_index;
  u32 context;
  u32 cursor;
};

define map_domains_get_reply
{
  u32 context;
  i32 retval;
  u32 cursor;
};

To avoid blocking the main thread for too long, the replies are now sent in client message queue size
chunks. The reply message returns VNET_API_ERROR_EAGAIN when there is more to read.
The API handler must also include a "cursor" that is used to the next call to the get function.

API handler example:
  REPLY_AND_DETAILS_MACRO (VL_API_MAP_DOMAINS_GET_REPLY, mm->domains,
  ({
    send_domain_details (cursor, rp, mp->context);
  }));

The macro starts from cursor and iterates through the pool
until vl_api_process_may_suspend() returns true or the iteration
reaches the end of the list.

Client Example:

cursor = 0
d = []
while True:
    rv, details = map_domains_get(cursor=cursor)
    d += details
    if rv.retval == 0 or rv.retval != -165:
        break
    cursor = rv.cursor

or the convenience iterator:
for x in vpp.details_iter(vpp.api.map_domains_get):
  pass

or

list(details_iter(map_domains_get))

Change-Id: Iad9f6b41b0ef886adb584c97708dd91cf552749e
Type: feature
Signed-off-by: Ole Troan <ot@cisco.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/src/vlibapi/api_helper_macros.h b/src/vlibapi/api_helper_macros.h
index b19d4f90f81..57502570f11 100644
--- a/src/vlibapi/api_helper_macros.h
+++ b/src/vlibapi/api_helper_macros.h
@@ -90,6 +90,15 @@ do {                                                                    \
     vl_api_send_msg (rp, (u8 *)rmp);                                    \
 } while(0);
 
+#define REPLY_MACRO_DETAILS4(t, rp, context, body)			\
+do {                                                                    \
+    rmp = vl_msg_api_alloc (sizeof (*rmp));                             \
+    rmp->_vl_msg_id = htons((t)+(REPLY_MSG_ID_BASE));                   \
+    rmp->context = context;                                             \
+    do {body;} while (0);                                               \
+    vl_api_send_msg (rp, (u8 *)rmp);                                    \
+} while(0);
+
 #define REPLY_MACRO3(t, n, body)                                        \
 do {                                                                    \
     vl_api_registration_t *rp;                                          \
@@ -153,6 +162,34 @@ do {                                                                    \
     vl_api_send_msg (rp, (u8 *)rmp);                                    \
 } while(0);
 
+#define REPLY_AND_DETAILS_MACRO(t, p, body)			\
+do {								\
+  vl_api_registration_t *rp;					\
+  rp = vl_api_client_index_to_registration (mp->client_index);	\
+  if (rp == 0)							\
+    return;							\
+  u32 cursor = clib_net_to_host_u32 (mp->cursor);		\
+  vlib_main_t *vm = vlib_get_main ();				\
+  f64 start = vlib_time_now (vm);				\
+  if (pool_is_free_index (p, cursor)) {				\
+    cursor = pool_next_index (p, cursor);			\
+    if (cursor == ~0)						\
+      rv = VNET_API_ERROR_INVALID_VALUE;			\
+  }								\
+  while (cursor != ~0) {					\
+    do {body;} while (0);					\
+    cursor = pool_next_index (p, cursor);			\
+    if (vl_api_process_may_suspend (vm, rp, start)) {   	\
+      if (cursor != ~0)						\
+        rv = VNET_API_ERROR_EAGAIN;				\
+      break;							\
+    }								\
+  }								\
+  REPLY_MACRO2 (t, ({						\
+    rmp->cursor = clib_host_to_net_u32 (cursor);		\
+  }));								\
+} while(0);
+
 /* "trust, but verify" */
 
 static inline uword