# OS-Ken application API

## OS-Ken application programming model

### Threads, events, and event queues

OS-Ken applications are single-threaded entities which implement various functionalities in OS-Ken. Events are messages between them.

OS-Ken applications send asynchronous events to each other. Besides that, there are some OS-Ken-internal event sources which are not OS-Ken applications. One of the examples of such event sources is the OpenFlow controller. While an event can currently contain arbitrary python objects, it's discouraged to pass complex objects (eg. unpickleable objects) between OS-Ken applications.

Each OS-Ken application has a receive queue for events. The queue is FIFO and preserves the order of events. Each OS-Ken application has a thread for event processing. The thread keeps 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 when blocking. While an event handler is blocked, no further events for the OS-Ken application will be processed.

There are kinds of events which are used to implement synchronous inter-application calls between OS-Ken applications. While such requests use the same machinery as ordinary events, their replies are put on a queue dedicated to the transaction to avoid deadlock.

While threads and queues are currently implemented with eventlet/greenlet, a direct use of them in a OS-Ken application is strongly discouraged.

### Contexts

Contexts are ordinary python objects shared among OS-Ken applications. The use of contexts is discouraged for new code.

## Create a OS-Ken application

A OS-Ken application is a python module which defines a subclass of os_ken.base.app_manager.OSKenApp. If two or more such classes are defined in a module, the first one (by name order) will be picked by app_manager. An OS-Ken application is singleton: only a single instance of a given OS-Ken application is supported.

## Observe events

A OS-Ken application can register itself to listen for specific events using os_ken.controller.handler.set_ev_cls decorator.

## Generate events

A OS-Ken application can raise events by calling appropriate os_ken.base.app_manager.OSKenApp's methods like send_event or send_event_to_observers.

## Event classes

An event class describes a OS-Ken event generated in the system. By convention, event class names are prefixed by "Event". Events are generated either by the core part of OS-Ken or OS-Ken applications. A OS-Ken application can register its interest for a specific type of event by providing a handler method using the os_ken.controller.handler.set_ev_cls decorator.

### OpenFlow event classes

os_ken.controller.ofp_event module exports event classes which describe receptions of OpenFlow messages from connected switches. By convention, they are named as os_ken.controller.ofp_event.EventOFPxxxx where xxxx is the name of the corresponding OpenFlow message. For example, EventOFPPacketIn for the packet-in message. The OpenFlow controller part of OS-Ken automatically decodes OpenFlow messages received from switches and send these events to OS-Ken applications which expressed an interest using os_ken.controller.handler.set_ev_cls. OpenFlow event classes are subclasses of the following class.

class os_ken.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 os_ken.controller.controller.Datapath instance which describes an OpenFlow switch from which we received this OpenFlow message.
  timestamp | Timestamp when Datapath instance generated this event.

  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.

## os_ken.base.app_manager.OSKenApp

See OS-Ken API Reference.

## os_ken.controller.handler.set_ev_cls

os_ken.controller.handler.set_ev_cls(ev_cls, dispatchers=None)

  A decorator for OSKen application to declare an event handler.

  Decorated method will become an event handler. ev_cls is an event class whose instances this OSKenApp 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
  --- | ---
  os_ken.controller.handler.HANDSHAKE_DISPATCHER | Sending and waiting for hello message
  os_ken.controller.handler.CONFIG_DISPATCHER | Version negotiated and sent features-request message
  os_ken.controller.handler.MAIN_DISPATCHER | Switch-features message received and sent set-config message
  os_ken.controller.handler.DEAD_DISPATCHER | Disconnect from the peer. Or disconnecting due to some unrecoverable errors.

## os_ken.controller.controller.Datapath

class os_ken.controller.controller.Datapath(socket, address)

  A class to describe an OpenFlow switch connected to this controller.

  An instance has the following attributes.

  Attribute | Description
  --- | ---
  id | 64-bit OpenFlow Datapath ID. Only available for os_ken.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, os_ken.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, os_ken.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

## os_ken.controller.event.EventBase

class os_ken.controller.event.EventBase

  The base of all event classes.

  A OSKen application can define its own event type by creating a subclass.

## os_ken.controller.event.EventRequestBase

class os_ken.controller.event.EventRequestBase

  The base class for synchronous request for OSKenApp.send_request.

## os_ken.controller.event.EventReplyBase

class os_ken.controller.event.EventReplyBase(dst)

  The base class for synchronous request reply for OSKenApp.send_reply.

## os_ken.controller.ofp_event.EventOFPStateChange

class os_ken.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 | os_ken.controller.controller.Datapath instance of the switch

## os_ken.controller.ofp_event.EventOFPPortStateChange

class os_ken.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 OSKen will send this event after updating `ports` dict of Datapath instances. An instance has at least the following attributes.

  Attribute | Description
  --- | ---
  datapath | os_ken.controller.controller.Datapath instance of the switch
  reason | one of OFPPR_*
  port_no | Port number which state was changed

## os_ken.controller.dpset.EventDP

class os_ken.controller.dpset.EventDP(dp, enter_leave)

  An event class to notify connect/disconnect of a switch.

  For OpenFlow switches, one can get the same notification by observing os_ken.controller.ofp_event.EventOFPStateChange. An instance has at least the following attributes.

  Attribute | Description
  --- | ---
  dp | A os_ken.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.

## os_ken.controller.dpset.EventPortAdd

class os_ken.controller.dpset.EventPortAdd(dp, port)

  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 os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

  Attribute | Description
  --- | ---
  dp | A os_ken.controller.controller.Datapath instance of the switch
  port | port number

## os_ken.controller.dpset.EventPortDelete

class os_ken.controller.dpset.EventPortDelete(dp, port)

  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 os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

  Attribute | Description
  --- | ---
  dp | A os_ken.controller.controller.Datapath instance of the switch
  port | port number

## os_ken.controller.dpset.EventPortModify

class os_ken.controller.dpset.EventPortModify(dp, new_port)

  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 os_ken.controller.ofp_event.EventOFPPortStatus. An instance has at least the following attributes.

  Attribute | Description
  --- | ---
  dp | A os_ken.controller.controller.Datapath instance of the switch
  port | port number

## os_ken.controller.network.EventNetworkPort

class os_ken.controller.network.EventNetworkPort(network_id, dpid, port_no, add_del)

  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.

## os_ken.controller.network.EventNetworkDel

class os_ken.controller.network.EventNetworkDel(network_id)

  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

## os_ken.controller.network.EventMacAddress

class os_ken.controller.network.EventMacAddress(dpid, port_no, network_id, mac_address, add_del)

  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.

## os_ken.controller.tunnels.EventTunnelKeyAdd

class os_ken.controller.tunnels.EventTunnelKeyAdd(network_id, tunnel_key)

  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

## os_ken.controller.tunnels.EventTunnelKeyDel

class os_ken.controller.tunnels.EventTunnelKeyDel(network_id, tunnel_key)

  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

## os_ken.controller.tunnels.EventTunnelPort

class os_ken.controller.tunnels.EventTunnelPort(dpid, port_no, remote_dpid, add_del)

  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.

this page last updated: 2026-04-10 03:11:34

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug