Ryu application API¶
Ryu application programming model¶
Threads, events, and event queues¶
Ryu applications are single-threaded entities which implement various functionalities in Ryu. Events are messages between them.
Ryu applications send asynchronous events each other. Besides that, there are some Ryu-internal event sources which are not Ryu applications. One of examples of such event sources is OpenFlow controller. While an event can currently contain arbitrary python objects, it's discouraged to pass complex objects (eg. unpickleable objects) between Ryu applications.
Each Ryu application has a receive queue for events. The queue is FIFO and preserves the order of events. Each Ryu application has a thread for event processing. The thread keep draining the receive queue by dequeueing an event and calling the appropritate event handler for the event type. Because the event handler is called in the context of the event processing thread, it should be careful for blocking. I.e. while an event handler is blocked, no further events for the Ryu application will be processed.
There are kinds of events which are used to implement synchronous inter-application calls between Ryu applications. While such requests uses the same machinary as ordinary events, their replies are put on a queue dedicated to the transaction to avoid deadlock.
While threads and queues is currently implemented with eventlet/greenlet, a direct use of them in a Ryu application is strongly discouraged.
Contexts¶
Contexts are ordinary python objects shared among Ryu applications. The use of contexts are discouraged for new code.
Create a Ryu application¶
A Ryu application is a python module which defines a subclass of ryu.base.app_manager.RyuApp. If two or more such classes are defined in a module, the first one (by name order) will be picked by app_manager. Ryu application is singleton: only single instance of a given Ryu application is supported.
Observe events¶
A Ryu application can register itself to listen for specific events using ryu.controller.handler.set_ev_cls decorator.
Generate events¶
A Ryu application can raise events by calling appropriate ryu.base.app_manager.RyuApp's methods like send_event or send_event_to_observers.
Event classes¶
An event class describes a Ryu event generated in the system. By convention, event class names are prefixed by "Event". Events are generated either by the core part of Ryu or Ryu applications. A Ryu application can register its interest for a specific type of event by providing a handler method using ryu.controller.handler.set_ev_cls decorator.
OpenFlow event classes¶
ryu.controller.ofp_event module exports event classes which describe receptions of OpenFlow messages from connected switches. By convention, they are named as ryu.controller.ofp_event.EventOFPxxxx where xxxx is the name of the corresponding OpenFlow message. For example, EventOFPPacketIn for packet-in message. The OpenFlow controller part of Ryu automatically decodes OpenFlow messages received from switches and send these events to Ryu applications which expressed an interest using ryu.controller.handler.set_ev_cls. OpenFlow event classes are subclass of the following class.
-
class
ryu.controller.ofp_event.EventOFPMsgBase(msg)¶ The base class of OpenFlow event class.
OpenFlow event classes have at least the following attributes.
Attribute Description msg An object which describes the corresponding OpenFlow message. msg.datapath A ryu.controller.controller.Datapath instance which describes an OpenFlow switch from which we received this OpenFlow message. The msg object has some more additional members whose values are extracted from the original OpenFlow message.
See OpenFlow protocol API Reference for more info about OpenFlow messages.
ryu.base.app_manager.RyuApp¶
See Ryu API Reference.
ryu.controller.handler.set_ev_cls¶
-
ryu.controller.handler.set_ev_cls(ev_cls, dispatchers=None)¶ A decorator for Ryu application to declare an event handler.
Decorated method will become an event handler. ev_cls is an event class whose instances this RyuApp wants to receive. dispatchers argument specifies one of the following negotiation phases (or a list of them) for which events should be generated for this handler. Note that, in case an event changes the phase, the phase before the change is used to check the interest.
Negotiation phase Description ryu.controller.handler.HANDSHAKE_DISPATCHER Sending and waiting for hello message ryu.controller.handler.CONFIG_DISPATCHER Version negotiated and sent features-request message ryu.controller.handler.MAIN_DISPATCHER Switch-features message received and sent set-config message ryu.controller.handler.DEAD_DISPATCHER Disconnect from the peer. Or disconnecting due to some unrecoverable errors.
ryu.controller.controller.Datapath¶
ryu.controller.event.EventBase¶
-
class
ryu.controller.event.EventBase¶ The base of all event classes.
A Ryu application can define its own event type by creating a subclass.
ryu.controller.event.EventRequestBase¶
-
class
ryu.controller.event.EventRequestBase¶ The base class for synchronous request for RyuApp.send_request.
ryu.controller.event.EventReplyBase¶
-
class
ryu.controller.event.EventReplyBase(dst)¶ The base class for synchronous request reply for RyuApp.send_reply.
ryu.controller.ofp_event.EventOFPStateChange¶
-
class
ryu.controller.ofp_event.EventOFPStateChange(dp)¶ An event class for negotiation phase change notification.
An instance of this class is sent to observer after changing the negotiation phase. An instance has at least the following attributes.
Attribute Description datapath ryu.controller.controller.Datapath instance of the switch
ryu.controller.ofp_event.EventOFPPortStateChange¶
-
class
ryu.controller.ofp_event.EventOFPPortStateChange(dp, reason, port_no)¶ An event class to notify the port state changes of Dtatapath instance.
This event performs like EventOFPPortStatus, but Ryu will send this event after updating
portsdict of Datapath instances. An instance has at least the following attributes.Attribute Description datapath ryu.controller.controller.Datapath instance of the switch reason one of OFPPR_* port_no Port number which state was changed