README written
[vsorcdistro/.git] / 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