docs/gettingstarted/developers/vpp_api_module.rst

   1 .. _vpp_api_module:
   2
   3 .. toctree::
   4
   5 VPP API module
   6 ==============
   7
   8 Overview
   9 ________
  10
  11 VPP API module allows communicating with VPP over shared memory interface. The API consists of 3 parts:
  12
  13 * common code - low-level API
  14 * generated code - high-level API
  15 * code generator - to generate your own high-level API e.g. for custom plugins
  16
  17 Common code
  18 ___________
  19
  20 **C**
  21
  22 C common code represents the basic, low-level API, providing functions to connect/disconnect, perform message discovery and send/receive messages. The C variant is in vapi.h.
  23
  24 **C++**
  25
  26 C++ is provided by vapi.hpp and contains high-level API templates, which are specialized by generated code.
  27
  28 Generated code
  29 ______________
  30
  31 Each API file present in the source tree is automatically translated to JSON file, which the code generator parses and generates either C (vapi_c_gen.py) or C++ (vapi_cpp_gen.py) code.
  32
  33 This can then be included in the client application and provides convenient way to interact with VPP. This includes:
  34
  35 * automatic byte-swapping
  36 * automatic request-response matching based on context
  37 * automatic casts to appropriate types (type-safety) when calling callbacks
  38 * automatic sending of control-pings for dump messages
  39
  40 The API supports two modes of operation:
  41
  42 * blocking
  43 * non-blocking
  44
  45 In blocking mode, whenever an operation is initiated, the code waits until it can finish. This means that when sending a message, the call blocks until the message can be written to shared memory. Similarly, receiving a message blocks until a message becomes available. On higher level, this also means that when doing a request (e.g. show_version), the call blocks until a response comes back (e.g. show_version_reply).
  46
  47 In non-blocking mode, these are decoupled, the API returns VAPI_EAGAIN whenever an operation cannot be performed and after sending a request, it's up to the client to wait for and process a response.
  48
  49 Code generator
  50 ______________
  51
  52 Python code generator comes in two flavors - C and C++ and generates high-level API headers. All the code is stored in the headers.
  53
  54 C Usage
  55 _______
  56
  57 **Low-level API**
  58
  59 Refer to inline API documentation in doxygen format in vapi.h header for description of functions. It's recommended to use the safer, high-level API provided by specialized headers (e.g. vpe.api.vapi.h or vpe.api.vapi.hpp).
  60
  61 **C high-level API**
  62
  63 *Callbacks*
  64
  65 The C high-level API is strictly callback-based for maximum efficiency. Whenever an operation is initiated a callback with a callback context is part of that operation. The callback is then invoked when the response (or multiple responses) arrive which are tied to the request. Also, callbacks are invoked whenever an event arrives, if such callback is registered. All the pointers to responses/events point to shared memory and are immediately freed after callback finishes so the client needs to extract/copy any data in which it is interested in.
  66
  67 **Blocking mode**
  68
  69 In simple blocking mode, the whole operation (being a simple request or a dump) is finished and it's callback is called (potentially multiple times for dumps) during function call.
  70
  71 Example pseudo-code for a simple request in this mode:
  72
  73 vapi_show_version(message, callback, callback_context)
  74
  75 #. generate unique internal context and assign it to message.header.context
  76 #. byteswap the message to network byte order
  77 #. send message to vpp (message is now consumed and vpp will free it)
  78 #. create internal "outstanding request context" which stores the callback, callback context and the internal context value
  79 #. call dispatch, which in this mode receives and processes responses until the internal "outstanding requests" queue is empty. In blocking mode, this queue always contains at most one item.
  80
  81 .. note::
  82
  83         It's possible for different - unrelated callbacks to be called before the response callbacks is called in cases where e.g. events are stored in shared memory queue.
  84
  85 **Non-blocking mode**
  86 In non-blocking mode, all the requests are only byte-swapped and the context information along with callbacks is stored locally (so in the above example, only steps 1-4 are executed and step 5 is skipped). Calling dispatch is up to the client application. This allows to alternate between sending/receiving messages or have a dedicated thread which calls dispatch.
  87
  88 C++ high level API
  89 __________________
  90
  91 **Callbacks**
  92
  93 In C++ API, the response is automatically tied to the corresponding Request, Dump or Event_registration object. Optionally a callback might be specified, which then gets called when the response is received.
  94
  95 .. note::
  96
  97         Responses take up shared memory space and should be freed either manually (in case of result sets) or automatically (by destroying the object owning them) when no longer needed. Once a Request or Dump object was executed, it cannot be re-sent, since the request itself (stores in shared memory) is consumed by vpp and inaccessible (set to nullptr) anymore.
  98
  99 C++ Usage
 100 _________
 101
 102 **Requests & dumps**
 103
 104 *Create an object of Connection type and call connect() to connect to vpp.*
 105
 106 #. Create an object of Request or Dump type using it's typedef (e.g. Show_version)
 107 #. Use get_request() to obtain and manipulate the underlying request if required.
 108 #. Issue execute() to send the request.
 109 #. Use either wait_for_response() or dispatch() to wait for the response.
 110 #. Use get_response_state() to get the state and get_response() to read the response.
 111
 112 **Events**
 113
 114 *Create a Connection and execute the appropriate Request to subscribe to events (e.g. Want_stats)*
 115
 116 #. Create an Event_registration with a template argument being the type of event you are interested in.
 117 #. Call dispatch() or wait_for_response() to wait for the event. A callback will be called when an event occurs (if passed to Event_registration() constructor). Alternatively, read the result set.
 118
 119 .. note::
 120
 121         Events stored in the result set take up space in shared memory and should be freed regularly (e.g. in the callback, once the event is processed).
 122