ryu/doc/source/ryu_app_api.rst

   1 *******************
   2 Ryu application API
   3 *******************
   4
   5 Ryu application programming model
   6 =================================
   7
   8 Threads, events, and event queues
   9 ---------------------------------
  10
  11 Ryu applications are single-threaded entities which implement
  12 various functionalities in Ryu.  Events are messages between them.
  13
  14 Ryu applications send asynchronous events to each other.
  15 Besides that, there are some Ryu-internal event sources which
  16 are not Ryu applications.  One of examples of such event sources
  17 is OpenFlow controller.
  18 While an event can currently contain arbitrary python objects,
  19 it's discouraged to pass complex objects (eg. unpickleable objects)
  20 between Ryu applications.
  21
  22 Each Ryu application has a receive queue for events.
  23 The queue is FIFO and preserves the order of events.
  24 Each Ryu application has a thread for event processing.
  25 The thread keeps draining the receive queue by dequeueing an event
  26 and calling the appropritate event handler for the event type.
  27 Because the event handler is called in the context of
  28 the event processing thread, it should be careful when blocking.
  29 While an event handler is blocked, no further events for
  30 the Ryu application will be processed.
  31
  32 There are kinds of events which are used to implement synchronous
  33 inter-application calls between Ryu applications.
  34 While such requests uses the same machinary as ordinary
  35 events, their replies are put on a queue dedicated to the transaction
  36 to avoid deadlock.
  37
  38 While threads and queues is currently implemented with eventlet/greenlet,
  39 a direct use of them in a Ryu application is strongly discouraged.
  40
  41 Contexts
  42 --------
  43 Contexts are ordinary python objects shared among Ryu applications.
  44 The use of contexts are discouraged for new code.
  45
  46 Create a Ryu application
  47 ========================
  48 A Ryu application is a python module which defines a subclass of
  49 ryu.base.app_manager.RyuApp.
  50 If two or more such classes are defined in a module, the first one
  51 (by name order) will be picked by app_manager.
  52 Ryu application is singleton: only single instance of a given Ryu
  53 application is supported.
  54
  55 Observe events
  56 ==============
  57 A Ryu application can register itself to listen for specific events
  58 using ryu.controller.handler.set_ev_cls decorator.
  59
  60 Generate events
  61 ===============
  62 A Ryu application can raise events by calling appropriate
  63 ryu.base.app_manager.RyuApp's methods like send_event or
  64 send_event_to_observers.
  65
  66 Event classes
  67 =============
  68 An event class describes a Ryu event generated in the system.
  69 By convention, event class names are prefixed by "Event".
  70 Events are generated either by the core part of Ryu or Ryu applications.
  71 A Ryu application can register its interest for a specific type of
  72 event by providing a handler method using
  73 ryu.controller.handler.set_ev_cls decorator.
  74
  75 OpenFlow event classes
  76 ----------------------
  77 ryu.controller.ofp_event module exports event classes which describe
  78 receptions of OpenFlow messages from connected switches.
  79 By convention, they are named as ryu.controller.ofp_event.EventOFPxxxx
  80 where xxxx is the name of the corresponding OpenFlow message.
  81 For example, EventOFPPacketIn for packet-in message.
  82 The OpenFlow controller part of Ryu automatically decodes OpenFlow messages
  83 received from switches and send these events to Ryu applications which
  84 expressed an interest using ryu.controller.handler.set_ev_cls.
  85 OpenFlow event classes are subclasses of the following class.
  86
  87 .. autoclass:: ryu.controller.ofp_event.EventOFPMsgBase
  88
  89 See :ref:`ofproto_ref` for more info about OpenFlow messages.
  90
  91 ryu.base.app_manager.RyuApp
  92 ===========================
  93
  94 See :ref:`api_ref`.
  95
  96 ryu.controller.handler.set_ev_cls
  97 =================================
  98
  99 .. autofunction:: ryu.controller.handler.set_ev_cls
 100
 101 ryu.controller.controller.Datapath
 102 ==================================
 103
 104 .. autoclass:: ryu.controller.controller.Datapath
 105
 106 ryu.controller.event.EventBase
 107 ==============================
 108
 109 .. autoclass:: ryu.controller.event.EventBase
 110
 111 ryu.controller.event.EventRequestBase
 112 =====================================
 113
 114 .. autoclass:: ryu.controller.event.EventRequestBase
 115
 116 ryu.controller.event.EventReplyBase
 117 ===================================
 118
 119 .. autoclass:: ryu.controller.event.EventReplyBase
 120
 121 ryu.controller.ofp_event.EventOFPStateChange
 122 ============================================
 123
 124 .. autoclass:: ryu.controller.ofp_event.EventOFPStateChange
 125
 126 ryu.controller.ofp_event.EventOFPPortStateChange
 127 ================================================
 128
 129 .. autoclass:: ryu.controller.ofp_event.EventOFPPortStateChange
 130
 131 ryu.controller.dpset.EventDP
 132 ============================
 133
 134 .. autoclass:: ryu.controller.dpset.EventDP
 135
 136 ryu.controller.dpset.EventPortAdd
 137 =================================
 138
 139 .. autoclass:: ryu.controller.dpset.EventPortAdd
 140
 141 ryu.controller.dpset.EventPortDelete
 142 ====================================
 143
 144 .. autoclass:: ryu.controller.dpset.EventPortDelete
 145
 146 ryu.controller.dpset.EventPortModify
 147 ====================================
 148
 149 .. autoclass:: ryu.controller.dpset.EventPortModify
 150
 151 ryu.controller.network.EventNetworkPort
 152 =======================================
 153
 154 .. autoclass:: ryu.controller.network.EventNetworkPort
 155
 156 ryu.controller.network.EventNetworkDel
 157 ======================================
 158
 159 .. autoclass:: ryu.controller.network.EventNetworkDel
 160
 161 ryu.controller.network.EventMacAddress
 162 ======================================
 163
 164 .. autoclass:: ryu.controller.network.EventMacAddress
 165
 166 ryu.controller.tunnels.EventTunnelKeyAdd
 167 ========================================
 168
 169 .. autoclass:: ryu.controller.tunnels.EventTunnelKeyAdd
 170
 171 ryu.controller.tunnels.EventTunnelKeyDel
 172 ========================================
 173
 174 .. autoclass:: ryu.controller.tunnels.EventTunnelKeyDel
 175
 176 ryu.controller.tunnels.EventTunnelPort
 177 ======================================
 178
 179 .. autoclass:: ryu.controller.tunnels.EventTunnelPort