int response_queue_size, vapi_mode_e mode,
bool handle_keepalives);
+/**
+ * @brief connect to vpp
+ *
+ * @param ctx opaque vapi context, must be allocated using vapi_ctx_alloc first
+ * @param name application name
+ * @param path shared memory prefix or path to unix socket
+ * @param max_outstanding_requests max number of outstanding requests queued
+ * @param response_queue_size size of the response queue
+ * @param mode mode of operation - blocking or nonblocking
+ * @param handle_keepalives - if true, automatically handle memclnt_keepalive
+ * @param use_uds - if true, use unix domain socket transport
+ *
+ * @return VAPI_OK on success, other error code on error
+ */
+vapi_error_e vapi_connect_ex (vapi_ctx_t ctx, const char *name,
+ const char *path, int max_outstanding_requests,
+ int response_queue_size, vapi_mode_e mode,
+ bool handle_keepalives, bool use_uds);
+
/**
* @brief connect to vpp from a client in same process
* @remark This MUST be called from a separate thread. If called
*/
vapi_error_e vapi_wait (vapi_ctx_t ctx);
+/**
+ * @brief pick next message sent by vpp and call the appropriate callback
+ *
+ * @note if using block mode, it will be blocked indefinitely until the next
+ * msg available. If using non-blocking mode, it will block for time_wait
+ * seconds until the next msg available if time_wait > 0, or does not block if
+ * time_wait == 0.
+ *
+ * @return VAPI_OK on success, other error code on error
+ */
+vapi_error_e vapi_dispatch_one_timedwait (vapi_ctx_t ctx, u32 wait_time);
+
/**
* @brief pick next message sent by vpp and call the appropriate callback
*
* @return VAPI_OK on success, other error code on error
*/
- vapi_error_e vapi_dispatch_one (vapi_ctx_t ctx);
+vapi_error_e vapi_dispatch_one (vapi_ctx_t ctx);
/**
* @brief loop vapi_dispatch_one until responses to all currently outstanding
*
* @note the dispatch loop is interrupted if any error is encountered or
* returned from the callback, in which case this error is returned as the
- * result of vapi_dispatch. In this case it might be necessary to call dispatch
- * again to process the remaining messages. Returning VAPI_EUSER from
- * a callback allows the user to break the dispatch loop (and distinguish
- * this case in the calling code from other failures). VAPI never returns
- * VAPI_EUSER on its own.
+ * result of vapi_dispatch. In this case it might be necessary to call
+ * dispatch again to process the remaining messages. Returning VAPI_EUSER
+ * from a callback allows the user to break the dispatch loop (and
+ * distinguish this case in the calling code from other failures). VAPI never
+ * returns VAPI_EUSER on its own.
*
* @return VAPI_OK on success, other error code on error
*/
- vapi_error_e vapi_dispatch (vapi_ctx_t ctx);
+vapi_error_e vapi_dispatch (vapi_ctx_t ctx);
/** generic vapi event callback */
- typedef vapi_error_e (*vapi_event_cb) (vapi_ctx_t ctx, void *callback_ctx,
- void *payload);
+typedef vapi_error_e (*vapi_event_cb) (vapi_ctx_t ctx, void *callback_ctx,
+ void *payload);
/**
* @brief set event callback to call when message with given id is dispatched
* @param callback callback
* @param callback_ctx context pointer stored and passed to callback
*/
- void vapi_set_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id,
- vapi_event_cb callback, void *callback_ctx);
+void vapi_set_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id,
+ vapi_event_cb callback, void *callback_ctx);
/**
* @brief clear event callback for given message id
* @param ctx opaque vapi context
* @param id message id
*/
- void vapi_clear_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id);
+void vapi_clear_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id);
/** generic vapi event callback */
- typedef vapi_error_e (*vapi_generic_event_cb) (vapi_ctx_t ctx,
- void *callback_ctx,
- vapi_msg_id_t id, void *msg);
+typedef vapi_error_e (*vapi_generic_event_cb) (vapi_ctx_t ctx,
+ void *callback_ctx,
+ vapi_msg_id_t id, void *msg);
/**
* @brief set generic event callback
*
* @param callback callback
* @param callback_ctx context pointer stored and passed to callback
*/
- void vapi_set_generic_event_cb (vapi_ctx_t ctx,
- vapi_generic_event_cb callback,
- void *callback_ctx);
+void vapi_set_generic_event_cb (vapi_ctx_t ctx, vapi_generic_event_cb callback,
+ void *callback_ctx);
/**
* @brief clear generic event callback
*
* @param ctx opaque vapi context
*/
- void vapi_clear_generic_event_cb (vapi_ctx_t ctx);
+void vapi_clear_generic_event_cb (vapi_ctx_t ctx);
+
+/**
+ * @brief signal RX thread to exit
+ *
+ * @note This adds a message to the client input queue that indicates that
+ * an RX thread should stop processing incoming messages and exit. If an
+ * application has an RX thread which sleeps while waiting for incoming
+ * messages using vapi_wait(), this call will allow the application to
+ * wake up from the vapi_wait() call and figure out that it should stop
+ * running.
+ *
+ * @param ctx opaque vapi context
+ */
+void vapi_stop_rx_thread (vapi_ctx_t ctx);
#ifdef __cplusplus
}