To improve maintainability, this patch moves the descriptions of "Ryu application API" into each source code.
Signed-off-by: IWASE Yusuke <[email protected]> --- doc/source/ryu_app_api.rst | 226 ++++--------------------------------------- ryu/controller/controller.py | 50 ++++++++++ ryu/controller/dpset.py | 65 +++++++++++++ ryu/controller/event.py | 16 ++- ryu/controller/handler.py | 27 ++++++ ryu/controller/network.py | 50 ++++++++++ ryu/controller/ofp_event.py | 21 ++++ ryu/controller/tunnels.py | 45 +++++++++ 8 files changed, 292 insertions(+), 208 deletions(-) diff --git a/doc/source/ryu_app_api.rst b/doc/source/ryu_app_api.rst index 323b4a9..67566c7 100644 --- a/doc/source/ryu_app_api.rst +++ b/doc/source/ryu_app_api.rst @@ -82,20 +82,10 @@ 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 have at least the following attributes. +OpenFlow event classes are subclass of the following class. -.. tabularcolumns:: |l|L| +.. autoclass:: ryu.controller.ofp_event.EventOFPMsgBase -============ ============================================================= -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 :ref:`ofproto_ref` for more info about OpenFlow messages. ryu.base.app_manager.RyuApp @@ -103,97 +93,30 @@ ryu.base.app_manager.RyuApp See :ref:`api_ref`. -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. - -.. tabularcolumns:: |l|L| - -=========================================== ================================== -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.handler.set_ev_cls +================================= + +.. autofunction:: ryu.controller.handler.set_ev_cls ryu.controller.controller.Datapath ================================== -A class to describe an OpenFlow switch connected to this controller. -An instance has the following attributes. - -.. tabularcolumns:: |l|L| - -====================================== ======================================= -Attribute Description -====================================== ======================================= -id 64-bit OpenFlow Datapath ID. - Only available for - ryu.controller.handler.MAIN_DISPATCHER - phase. -ofproto A module which exports OpenFlow - definitions, mainly constants appeared - in the specification, for the - negotiated OpenFlow version. For - example, ryu.ofproto.ofproto_v1_0 for - OpenFlow 1.0. -ofproto_parser A module which exports OpenFlow wire - message encoder and decoder for the - negotiated OpenFlow version. For - example, ryu.ofproto.ofproto_v1_0_parser - for OpenFlow 1.0. -ofproto_parser.OFPxxxx(datapath, ....) A callable to prepare an OpenFlow - message for the given switch. It can - be sent with Datapath.send_msg later. - xxxx is a name of the message. For - example OFPFlowMod for flow-mod - message. Arguemnts depend on the - message. -set_xid(self, msg) Generate an OpenFlow XID and put it - in msg.xid. -send_msg(self, msg) Queue an OpenFlow message to send to - the corresponding switch. If msg.xid - is None, set_xid is automatically - called on the message before queueing. -send_packet_out deprecated -send_flow_mod deprecated -send_flow_del deprecated -send_delete_all_flows deprecated -send_barrier Queue an OpenFlow barrier message to - send to the switch. -send_nxt_set_flow_format deprecated -is_reserved_port deprecated -====================================== ======================================= +.. autoclass:: ryu.controller.controller.Datapath ryu.controller.event.EventBase ============================== -The base of all event classes. -A Ryu application can define its own event type by creating a subclass. +.. autoclass:: ryu.controller.event.EventBase ryu.controller.event.EventRequestBase ===================================== -The base class for synchronous request for RyuApp.send_request. +.. autoclass:: ryu.controller.event.EventRequestBase ryu.controller.event.EventReplyBase =================================== -The base class for synchronous request reply for RyuApp.send_reply. +.. autoclass:: ryu.controller.event.EventReplyBase ryu.controller.ofp_event.EventOFPStateChange ============================================ @@ -208,158 +131,49 @@ ryu.controller.ofp_event.EventOFPPortStateChange ryu.controller.dpset.EventDP ============================ -An event class to notify connect/disconnect of a switch. -For OpenFlow switches, one can get the same notification by observing -ryu.controller.ofp_event.EventOFPStateChange. -An instance has at least the following attributes. - -========= ==================================================================== -Attribute Description -========= ==================================================================== -dp A ryu.controller.controller.Datapath instance of the switch -enter True when the switch connected to our controller. False for - disconnect. -========= ==================================================================== +.. autoclass:: ryu.controller.dpset.EventDP ryu.controller.dpset.EventPortAdd ================================= -An event class for switch port status notification. -This event is generated when a new port is added to a switch. -For OpenFlow switches, one can get the same notification by observing -ryu.controller.ofp_event.EventOFPPortStatus. -An instance has at least the following attributes. - -========= ==================================================================== -Attribute Description -========= ==================================================================== -dp A ryu.controller.controller.Datapath instance of the switch -port port number -========= ==================================================================== +.. autoclass:: ryu.controller.dpset.EventPortAdd ryu.controller.dpset.EventPortDelete ==================================== -An event class for switch port status notification. -This event is generated when a port is removed from a switch. -For OpenFlow switches, one can get the same notification by observing -ryu.controller.ofp_event.EventOFPPortStatus. -An instance has at least the following attributes. - -========= ==================================================================== -Attribute Description -========= ==================================================================== -dp A ryu.controller.controller.Datapath instance of the switch -port port number -========= ==================================================================== +.. autoclass:: ryu.controller.dpset.EventPortDelete ryu.controller.dpset.EventPortModify ==================================== -An event class for switch port status notification. -This event is generated when some attribute of a port is changed. -For OpenFlow switches, one can get the same notification by observing -ryu.controller.ofp_event.EventOFPPortStatus. -An instance has at least the following attributes. - -========= ==================================================================== -Attribute Description -========= ==================================================================== -dp A ryu.controller.controller.Datapath instance of the switch -port port number -========= ==================================================================== +.. autoclass:: ryu.controller.dpset.EventPortModify ryu.controller.network.EventNetworkPort ======================================= -An event class for notification of port arrival and deperture. -This event is generated when a port is introduced to or removed from a network -by the REST API. -An instance has at least the following attributes. - -========== =================================================================== -Attribute Description -========== =================================================================== -network_id Network ID -dpid OpenFlow Datapath ID of the switch to which the port belongs. -port_no OpenFlow port number of the port -add_del True for adding a port. False for removing a port. -========== =================================================================== +.. autoclass:: ryu.controller.network.EventNetworkPort ryu.controller.network.EventNetworkDel ====================================== -An event class for network deletion. -This event is generated when a network is deleted by the REST API. -An instance has at least the following attributes. - -========== =================================================================== -Attribute Description -========== =================================================================== -network_id Network ID -========== =================================================================== +.. autoclass:: ryu.controller.network.EventNetworkDel ryu.controller.network.EventMacAddress ====================================== -An event class for end-point MAC address registration. -This event is generated when a end-point MAC address is updated -by the REST API. -An instance has at least the following attributes. - -=========== ================================================================== -Attribute Description -=========== ================================================================== -network_id Network ID -dpid OpenFlow Datapath ID of the switch to which the port belongs. -port_no OpenFlow port number of the port -mac_address The old MAC address of the port if add_del is False. Otherwise - the new MAC address. -add_del False if this event is a result of a port removal. Otherwise - True. -=========== ================================================================== +.. autoclass:: ryu.controller.network.EventMacAddress ryu.controller.tunnels.EventTunnelKeyAdd ======================================== -An event class for tunnel key registration. -This event is generated when a tunnel key is registered or updated -by the REST API. -An instance has at least the following attributes. - -=========== ================================================================== -Attribute Description -=========== ================================================================== -network_id Network ID -tunnel_key Tunnel Key -=========== ================================================================== +.. autoclass:: ryu.controller.tunnels.EventTunnelKeyAdd ryu.controller.tunnels.EventTunnelKeyDel ======================================== -An event class for tunnel key registration. -This event is generated when a tunnel key is removed by the REST API. -An instance has at least the following attributes. - -=========== ================================================================== -Attribute Description -=========== ================================================================== -network_id Network ID -tunnel_key Tunnel Key -=========== ================================================================== +.. autoclass:: ryu.controller.tunnels.EventTunnelKeyDel ryu.controller.tunnels.EventTunnelPort ====================================== -An event class for tunnel port registration. -This event is generated when a tunnel port is added or removed by the REST API. -An instance has at least the following attributes. - -=========== ================================================================== -Attribute Description -=========== ================================================================== -dpid OpenFlow Datapath ID -port_no OpenFlow port number -remote_dpid OpenFlow port number of the tunnel peer -add_del True for adding a tunnel. False for removal. -=========== ================================================================== +.. autoclass:: ryu.controller.tunnels.EventTunnelPort diff --git a/ryu/controller/controller.py b/ryu/controller/controller.py index 177b289..f1ba45c 100644 --- a/ryu/controller/controller.py +++ b/ryu/controller/controller.py @@ -125,6 +125,56 @@ def _deactivate(method): class Datapath(ofproto_protocol.ProtocolDesc): + """ + A class to describe an OpenFlow switch connected to this controller. + + An instance has the following attributes. + + .. tabularcolumns:: |l|L| + + ==================================== ====================================== + Attribute Description + ==================================== ====================================== + id 64-bit OpenFlow Datapath ID. + Only available for + ryu.controller.handler.MAIN_DISPATCHER + phase. + ofproto A module which exports OpenFlow + definitions, mainly constants appeared + in the specification, for the + negotiated OpenFlow version. For + example, ryu.ofproto.ofproto_v1_0 for + OpenFlow 1.0. + ofproto_parser A module which exports OpenFlow wire + message encoder and decoder for the + negotiated OpenFlow version. + For example, + ryu.ofproto.ofproto_v1_0_parser + for OpenFlow 1.0. + ofproto_parser.OFPxxxx(datapath,...) A callable to prepare an OpenFlow + message for the given switch. It can + be sent with Datapath.send_msg later. + xxxx is a name of the message. For + example OFPFlowMod for flow-mod + message. Arguemnts depend on the + message. + set_xid(self, msg) Generate an OpenFlow XID and put it + in msg.xid. + send_msg(self, msg) Queue an OpenFlow message to send to + the corresponding switch. If msg.xid + is None, set_xid is automatically + called on the message before queueing. + send_packet_out deprecated + send_flow_mod deprecated + send_flow_del deprecated + send_delete_all_flows deprecated + send_barrier Queue an OpenFlow barrier message to + send to the switch. + send_nxt_set_flow_format deprecated + is_reserved_port deprecated + ==================================== ====================================== + """ + def __init__(self, socket, address): super(Datapath, self).__init__() diff --git a/ryu/controller/dpset.py b/ryu/controller/dpset.py index 1ec6a33..5af6835 100644 --- a/ryu/controller/dpset.py +++ b/ryu/controller/dpset.py @@ -44,6 +44,23 @@ class EventDPBase(event.EventBase): class EventDP(EventDPBase): + """ + An event class to notify connect/disconnect of a switch. + + For OpenFlow switches, one can get the same notification by observing + ryu.controller.ofp_event.EventOFPStateChange. + An instance has at least the following attributes. + + ========= ================================================================= + Attribute Description + ========= ================================================================= + dp A ryu.controller.controller.Datapath instance of the switch + enter True when the switch connected to our controller. False for + disconnect. + ports A list of port instances. + ========= ================================================================= + """ + def __init__(self, dp, enter_leave): # enter_leave # True: dp entered @@ -67,16 +84,64 @@ class EventPortBase(EventDPBase): class EventPortAdd(EventPortBase): + """ + An event class for switch port status "ADD" notification. + + This event is generated when a new port is added to a switch. + For OpenFlow switches, one can get the same notification by observing + ryu.controller.ofp_event.EventOFPPortStatus. + An instance has at least the following attributes. + + ========= ================================================================= + Attribute Description + ========= ================================================================= + dp A ryu.controller.controller.Datapath instance of the switch + port port number + ========= ================================================================= + """ + def __init__(self, dp, port): super(EventPortAdd, self).__init__(dp, port) class EventPortDelete(EventPortBase): + """ + An event class for switch port status "DELETE" notification. + + This event is generated when a port is removed from a switch. + For OpenFlow switches, one can get the same notification by observing + ryu.controller.ofp_event.EventOFPPortStatus. + An instance has at least the following attributes. + + ========= ================================================================= + Attribute Description + ========= ================================================================= + dp A ryu.controller.controller.Datapath instance of the switch + port port number + ========= ================================================================= + """ + def __init__(self, dp, port): super(EventPortDelete, self).__init__(dp, port) class EventPortModify(EventPortBase): + """ + An event class for switch port status "MODIFY" notification. + + This event is generated when some attribute of a port is changed. + For OpenFlow switches, one can get the same notification by observing + ryu.controller.ofp_event.EventOFPPortStatus. + An instance has at least the following attributes. + + ========= ==================================================================== + Attribute Description + ========= ==================================================================== + dp A ryu.controller.controller.Datapath instance of the switch + port port number + ========= ==================================================================== + """ + def __init__(self, dp, new_port): super(EventPortModify, self).__init__(dp, new_port) diff --git a/ryu/controller/event.py b/ryu/controller/event.py index a90bf66..e9d4921 100644 --- a/ryu/controller/event.py +++ b/ryu/controller/event.py @@ -16,11 +16,20 @@ class EventBase(object): - # Nothing yet - pass + """ + The base of all event classes. + + A Ryu application can define its own event type by creating a subclass. + """ + + def __init__(self): + super(EventBase, self).__init__() class EventRequestBase(EventBase): + """ + The base class for synchronous request for RyuApp.send_request. + """ def __init__(self): super(EventRequestBase, self).__init__() self.dst = None # app.name of provide the event. @@ -30,6 +39,9 @@ class EventRequestBase(EventBase): class EventReplyBase(EventBase): + """ + The base class for synchronous request reply for RyuApp.send_reply. + """ def __init__(self, dst): super(EventReplyBase, self).__init__() self.dst = dst diff --git a/ryu/controller/handler.py b/ryu/controller/handler.py index a0782a1..f1fb707 100644 --- a/ryu/controller/handler.py +++ b/ryu/controller/handler.py @@ -47,6 +47,33 @@ class _Caller(object): # should be named something like 'observe_event' def 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. + + .. tabularcolumns:: |l|L| + + =========================================== =============================== + 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. + =========================================== =============================== + """ def _set_ev_cls_dec(handler): if 'callers' not in dir(handler): handler.callers = {} diff --git a/ryu/controller/network.py b/ryu/controller/network.py index 9b9baa4..83c91b4 100644 --- a/ryu/controller/network.py +++ b/ryu/controller/network.py @@ -31,12 +31,42 @@ class MacAddressAlreadyExist(ryu_exc.RyuException): class EventNetworkDel(event.EventBase): + """ + An event class for network deletion. + + This event is generated when a network is deleted by the REST API. + An instance has at least the following attributes. + + ========== =================================================================== + Attribute Description + ========== =================================================================== + network_id Network ID + ========== =================================================================== + """ + def __init__(self, network_id): super(EventNetworkDel, self).__init__() self.network_id = network_id class EventNetworkPort(event.EventBase): + """ + An event class for notification of port arrival and deperture. + + This event is generated when a port is introduced to or removed from a + network by the REST API. + An instance has at least the following attributes. + + ========== ================================================================ + Attribute Description + ========== ================================================================ + network_id Network ID + dpid OpenFlow Datapath ID of the switch to which the port belongs. + port_no OpenFlow port number of the port + add_del True for adding a port. False for removing a port. + ========== ================================================================ + """ + def __init__(self, network_id, dpid, port_no, add_del): super(EventNetworkPort, self).__init__() self.network_id = network_id @@ -46,6 +76,26 @@ class EventNetworkPort(event.EventBase): class EventMacAddress(event.EventBase): + """ + An event class for end-point MAC address registration. + + This event is generated when a end-point MAC address is updated + by the REST API. + An instance has at least the following attributes. + + =========== =============================================================== + Attribute Description + =========== =============================================================== + network_id Network ID + dpid OpenFlow Datapath ID of the switch to which the port belongs. + port_no OpenFlow port number of the port + mac_address The old MAC address of the port if add_del is False. Otherwise + the new MAC address. + add_del False if this event is a result of a port removal. Otherwise + True. + =========== =============================================================== + """ + def __init__(self, dpid, port_no, network_id, mac_address, add_del): super(EventMacAddress, self).__init__() assert network_id is not None diff --git a/ryu/controller/ofp_event.py b/ryu/controller/ofp_event.py index 8c990aa..6b1c8b3 100644 --- a/ryu/controller/ofp_event.py +++ b/ryu/controller/ofp_event.py @@ -27,6 +27,25 @@ from . import event class EventOFPMsgBase(event.EventBase): + """ + The base class of OpenFlow event class. + + OpenFlow event classes have at least the following attributes. + + .. tabularcolumns:: |l|L| + + ============ ============================================================== + 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. + """ def __init__(self, msg): super(EventOFPMsgBase, self).__init__() self.msg = msg @@ -83,6 +102,7 @@ for ofp_mods in ofproto.get_ofp_modules().values(): class EventOFPStateChange(event.EventBase): """ 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. @@ -101,6 +121,7 @@ class EventOFPStateChange(event.EventBase): class EventOFPPortStateChange(event.EventBase): """ 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 ``ports`` dict of Datapath instances. An instance has at least the following attributes. diff --git a/ryu/controller/tunnels.py b/ryu/controller/tunnels.py index 0a94673..61f0c16 100644 --- a/ryu/controller/tunnels.py +++ b/ryu/controller/tunnels.py @@ -43,16 +43,61 @@ class EventTunnelKeyBase(event.EventBase): class EventTunnelKeyAdd(EventTunnelKeyBase): + """ + An event class for tunnel key registration. + + This event is generated when a tunnel key is registered or updated + by the REST API. + An instance has at least the following attributes. + + =========== =============================================================== + Attribute Description + =========== =============================================================== + network_id Network ID + tunnel_key Tunnel Key + =========== =============================================================== + """ + def __init__(self, network_id, tunnel_key): super(EventTunnelKeyAdd, self).__init__(network_id, tunnel_key) class EventTunnelKeyDel(EventTunnelKeyBase): + """ + An event class for tunnel key registration. + + This event is generated when a tunnel key is removed by the REST API. + An instance has at least the following attributes. + + =========== =============================================================== + Attribute Description + =========== =============================================================== + network_id Network ID + tunnel_key Tunnel Key + =========== =============================================================== + """ + def __init__(self, network_id, tunnel_key): super(EventTunnelKeyDel, self).__init__(network_id, tunnel_key) class EventTunnelPort(event.EventBase): + """ + An event class for tunnel port registration. + + This event is generated when a tunnel port is added or removed + by the REST API. + An instance has at least the following attributes. + + =========== =============================================================== + Attribute Description + =========== =============================================================== + dpid OpenFlow Datapath ID + port_no OpenFlow port number + remote_dpid OpenFlow port number of the tunnel peer + add_del True for adding a tunnel. False for removal. + =========== =============================================================== + """ def __init__(self, dpid, port_no, remote_dpid, add_del): super(EventTunnelPort, self).__init__() self.dpid = dpid -- 2.7.4 ------------------------------------------------------------------------------ Mobile security can be enabling, not merely restricting. Employees who bring their own devices (BYOD) to work are irked by the imposition of MDM restrictions. Mobile Device Manager Plus allows you to control only the apps on BYO-devices by containerizing them, leaving personal data untouched! https://ad.doubleclick.net/ddm/clk/304595813;131938128;j _______________________________________________ Ryu-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/ryu-devel
