OS-Ken 应用 API¶

OS-Ken 应用编程模型¶

线程、事件和事件队列¶

OS-Ken 应用是单线程实体，它们在 OS-Ken 中实现各种功能。事件是它们之间的消息。

OS-Ken 应用之间发送异步事件。除此之外，还有一些 OS-Ken 内部事件源，它们不是 OS-Ken 应用。OpenFlow 控制器就是一个这样的事件源的例子。虽然事件当前可以包含任意 Python 对象，但不建议在 OS-Ken 应用之间传递复杂对象（例如，不可 pickle 的对象）。

每个 OS-Ken 应用都有一个用于接收事件的队列。队列是 FIFO（先进先出）的，并保留事件的顺序。每个 OS-Ken 应用都有一个线程来处理事件。该线程通过从接收队列中提取事件并调用事件类型的适当事件处理程序来持续地清空接收队列。由于事件处理程序是在事件处理线程的上下文中调用的，因此在阻塞时应小心。当事件处理程序被阻塞时，OS-Ken 应用将不会处理任何进一步的事件。

存在用于实现 OS-Ken 应用之间同步应用间调用的事件类型。虽然这些请求使用与普通事件相同的机制，但它们的回复被放置在一个专用于事务的队列中，以避免死锁。

虽然线程和队列当前使用 eventlet/greenlet 实现，但强烈建议不要在 OS-Ken 应用中直接使用它们。

上下文¶

上下文是在 OS-Ken 应用之间共享的普通 Python 对象。不建议在新代码中使用上下文。

创建一个 OS-Ken 应用¶

一个 OS-Ken 应用是一个 Python 模块，它定义了 os_ken.base.app_manager.OSKenApp 的子类。如果一个模块中定义了两个或多个此类类，则 app_manager 将按名称顺序选择第一个类。一个 OS-Ken 应用是单例：仅支持给定 OS-Ken 应用的单个实例。

观察事件¶

一个 OS-Ken 应用可以使用 os_ken.controller.handler.set_ev_cls 装饰器注册自身以监听特定事件。

生成事件¶

一个 OS-Ken 应用可以通过调用适当的 os_ken.base.app_manager.OSKenApp 方法（如 send_event 或 send_event_to_observers）来引发事件。

事件类¶

一个事件类描述了在系统中生成的 OS-Ken 事件。按照惯例，事件类名称以“Event”为前缀。事件由 OS-Ken 的核心部分或 OS-Ken 应用生成。一个 OS-Ken 应用可以通过使用 os_ken.controller.handler.set_ev_cls 装饰器提供一个处理程序方法来注册其对特定类型事件的兴趣。

OpenFlow 事件类¶

os_ken.controller.ofp_event 模块导出事件类，这些类描述了从连接的交换机接收到的 OpenFlow 消息。按照惯例，它们命名为 os_ken.controller.ofp_event.EventOFPxxxx，其中 xxxx 是相应的 OpenFlow 消息的名称。例如，EventOFPPacketIn 用于 packet-in 消息。OS-Ken 的 OpenFlow 控制器部分会自动解码从交换机接收到的 OpenFlow 消息，并将这些事件发送到使用 os_ken.controller.handler.set_ev_cls 表达兴趣的 OS-Ken 应用。OpenFlow 事件类是以下类的子类。

class os_ken.controller.ofp_event.EventOFPMsgBase(msg)¶

OpenFlow 事件类的基类。

OpenFlow 事件类至少具有以下属性。

属性	描述
msg	描述相应 OpenFlow 消息的对象。
msg.datapath	一个 os_ken.controller.controller.Datapath 实例，描述了我们从其接收到此 OpenFlow 消息的 OpenFlow 交换机。
timestamp	Datapath 实例生成此事件的时间戳。

msg 对象还有一些额外的成员，其值是从原始 OpenFlow 消息中提取的。

有关 OpenFlow 消息的更多信息，请参阅 OpenFlow 协议 API 参考。

os_ken.base.app_manager.OSKenApp¶

参阅 OS-Ken API 参考。

os_ken.controller.handler.set_ev_cls¶

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

OSKen 应用声明事件处理程序的装饰器。

装饰的方法将成为事件处理程序。ev_cls 是 OSKenApp 希望接收的事件类的实例。dispatchers 参数指定以下协商阶段之一（或其列表），应该为此处理程序生成事件。请注意，如果事件更改了阶段，则用于检查兴趣的是更改之前的阶段。

协商阶段	描述
os_ken.controller.handler.HANDSHAKE_DISPATCHER	发送和等待 hello 消息
os_ken.controller.handler.CONFIG_DISPATCHER	版本协商完成并发送 features-request 消息
os_ken.controller.handler.MAIN_DISPATCHER	接收 switch-features 消息并发送 set-config 消息
os_ken.controller.handler.DEAD_DISPATCHER	与对等端断开连接。或者由于某些无法恢复的错误而断开连接。

os_ken.controller.controller.Datapath¶

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

一个描述连接到此控制器的 OpenFlow 交换机的类。

一个实例具有以下属性。

属性	描述
id	64 位 OpenFlow Datapath ID。仅在 os_ken.controller.handler.MAIN_DISPATCHER 阶段可用。
ofproto	一个模块，它导出 OpenFlow 定义，主要是规范中出现的常量，用于协商的 OpenFlow 版本。例如，OpenFlow 1.0 的 os_ken.ofproto.ofproto_v1_0。
ofproto_parser	一个模块，它导出 OpenFlow 线路消息编码器和解码器，用于协商的 OpenFlow 版本。例如，OpenFlow 1.0 的 os_ken.ofproto.ofproto_v1_0_parser。
ofproto_parser.OFPxxxx(datapath,...)	一个可调用对象，用于为给定的交换机准备 OpenFlow 消息。可以使用 Datapath.send_msg 稍后发送它。xxxx 是消息的名称。例如，flow-mod 消息的 OFPFlowMod。参数取决于消息。
set_xid(self, msg)	生成 OpenFlow XID 并将其放入 msg.xid 中。
send_msg(self, msg)	将 OpenFlow 消息排队发送到相应的交换机。如果 msg.xid 为 None，则在排队之前会自动在消息上调用 set_xid。
send_packet_out	deprecated
send_flow_mod	deprecated
send_flow_del	deprecated
send_delete_all_flows	deprecated
send_barrier	将 OpenFlow barrier 消息排队发送到交换机。
send_nxt_set_flow_format	deprecated
is_reserved_port	deprecated

os_ken.controller.event.EventBase¶

class os_ken.controller.event.EventBase¶

所有事件类的基类。

OSKen 应用可以通过创建子类来定义自己的事件类型。

os_ken.controller.event.EventRequestBase¶

class os_ken.controller.event.EventRequestBase¶: OSKenApp.send_request 的同步请求的基类。

os_ken.controller.event.EventReplyBase¶

class os_ken.controller.event.EventReplyBase(dst)¶: OSKenApp.send_reply 的同步请求回复的基类。

os_ken.controller.ofp_event.EventOFPStateChange¶

class os_ken.controller.ofp_event.EventOFPStateChange(dp)¶

一个用于协商阶段更改通知的事件类。

在更改协商阶段后，会向观察者发送此类的实例。该实例至少具有以下属性。

属性	描述
datapath	交换机的 os_ken.controller.controller.Datapath 实例

os_ken.controller.ofp_event.EventOFPPortStateChange¶

class os_ken.controller.ofp_event.EventOFPPortStateChange(dp, reason, port_no)¶

一个事件类，用于通知 Datapath 实例的端口状态更改。

此事件类似于 EventOFPPortStatus，但 OSKen 会在更新 Datapath 实例的 ports 字典后发送此事件。该实例至少具有以下属性。

属性	描述
datapath	交换机的 os_ken.controller.controller.Datapath 实例
reason	OFPPR_* 中的一个
port_no	状态已更改的端口号

os_ken.controller.dpset.EventDP¶

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

一个事件类，用于通知交换机的连接/断开连接。

对于 OpenFlow 交换机，可以通过观察 os_ken.controller.ofp_event.EventOFPStateChange 获得相同的通知。该实例至少具有以下属性。

属性	描述
dp	交换机的 os_ken.controller.controller.Datapath 实例
enter	如果交换机连接到我们的控制器，则为 True。断开连接为 False。
ports	端口实例列表。

os_ken.controller.dpset.EventPortAdd¶

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

一个事件类，用于交换机端口状态“ADD”通知。

当将新端口添加到交换机时，会生成此事件。对于 OpenFlow 交换机，可以通过观察 os_ken.controller.ofp_event.EventOFPPortStatus 获得相同的通知。该实例至少具有以下属性。

属性	描述
dp	交换机的 os_ken.controller.controller.Datapath 实例
port	端口号

os_ken.controller.dpset.EventPortDelete¶

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

一个事件类，用于交换机端口状态“DELETE”通知。

当从交换机中删除端口时，会生成此事件。对于 OpenFlow 交换机，可以通过观察 os_ken.controller.ofp_event.EventOFPPortStatus 获得相同的通知。该实例至少具有以下属性。

属性	描述
dp	交换机的 os_ken.controller.controller.Datapath 实例
port	端口号

os_ken.controller.dpset.EventPortModify¶

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

一个事件类，用于交换机端口状态“MODIFY”通知。

当端口的某些属性发生更改时，会生成此事件。对于 OpenFlow 交换机，可以通过观察 os_ken.controller.ofp_event.EventOFPPortStatus 获得相同的通知。该实例至少具有以下属性。

属性	描述
dp	交换机的 os_ken.controller.controller.Datapath 实例
port	端口号

os_ken.controller.network.EventNetworkPort¶

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

端口到达和离开的事件类。

当端口通过 REST API 添加到或从网络中移除时，会生成此事件。一个实例至少具有以下属性。

属性	描述
network_id	网络 ID
dpid	端口所属交换机的 OpenFlow 数据路径 ID。
port_no	端口的 OpenFlow 端口号
add_del	添加端口为 True。移除端口为 False。

os_ken.controller.network.EventNetworkDel¶

class os_ken.controller.network.EventNetworkDel(network_id)¶

网络删除的事件类。

当网络通过 REST API 删除时，会生成此事件。一个实例至少具有以下属性。

属性	描述
network_id	网络 ID

os_ken.controller.network.EventMacAddress¶

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

端点 MAC 地址注册的事件类。

当端点 MAC 地址通过 REST API 更新时，会生成此事件。一个实例至少具有以下属性。

属性	描述
network_id	网络 ID
dpid	端口所属交换机的 OpenFlow 数据路径 ID。
port_no	端口的 OpenFlow 端口号
mac_address	如果 add_del 为 False，则为端口的旧 MAC 地址。否则为新的 MAC 地址。
add_del	如果此事件是端口移除的结果，则为 False。否则为 True。

os_ken.controller.tunnels.EventTunnelKeyAdd¶

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

隧道密钥注册的事件类。

当隧道密钥通过 REST API 注册或更新时，会生成此事件。一个实例至少具有以下属性。

属性	描述
network_id	网络 ID
tunnel_key	隧道密钥

os_ken.controller.tunnels.EventTunnelKeyDel¶

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