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, 22 insertions, 0 deletions

diff --git a/src/vlibmemory/api.h b/src/vlibmemory/api.h
index 6cd645bb1d5..662805373ba 100644
--- a/src/vlibmemory/api.h
+++ b/src/vlibmemory/api.h
@@ -53,6 +53,28 @@ vl_api_can_send_msg (vl_api_registration_t * rp)
     return vl_mem_api_can_send (rp->vl_input_queue);
 }
 
+/*
+ * Suggests to an API handler to relinguish control. Currently limits
+ * an handler to a maximum of 1ms or it earlier if the client queue is
+ * full.
+ *
+ * May be enhanced in the future based on other performance
+ * characteristics of the main thread.
+ */
+#define VL_API_MAX_TIME_IN_HANDLER 0.001	/* 1 ms */
+always_inline int
+vl_api_process_may_suspend (vlib_main_t * vm, vl_api_registration_t * rp,
+			    f64 start)
+{
+  /* Is client queue full (leave space for reply message) */
+  if (rp->registration_type <= REGISTRATION_TYPE_SHMEM &&
+      rp->vl_input_queue->cursize + 1 >= rp->vl_input_queue->maxsize)
+    return true;
+  if (vlib_time_now (vm) > start + VL_API_MAX_TIME_IN_HANDLER)
+    return true;
+  return false;
+}
+
 always_inline vl_api_registration_t *
 vl_api_client_index_to_registration (u32 index)
 {