core

Documentation

Overview

Package core provides connectivity to VPP via the adapter: sends and receives the messages to/from VPP, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP.

The interface_plugin APIs the core exposes is tied to a connection: Connect provides a connection, that cane be later used to request an API channel via NewAPIChannel / NewAPIChannelBuffered functions:

conn, err := govpp.Connect()
if err != nil {
	// handle error!
}
defer conn.Disconnect()

ch, err := conn.NewAPIChannel()
if err != nil {
	// handle error!
}
defer ch.Close()

Note that one application can open only one connection, that can serve multiple API channels.

The API offers two ways of communication with govpp core: using Go channels, or using convenient function wrappers over the Go channels. The latter should be sufficient for most of the use cases.

The entry point to the API is the Channel structure, that can be obtained from the existing connection using the NewAPIChannel or NewAPIChannelBuffered functions:

conn, err := govpp.Connect()
if err != nil {
	// handle error!
}
defer conn.Disconnect()

ch, err := conn.NewAPIChannel()
if err != nil {
	// handle error!
}
defer ch.Close()

Simple Request-Reply API

The simple version of the API is based on blocking SendRequest / ReceiveReply calls, where a single request message is sent to VPP and a single reply message is filled in when the reply comes from VPP:

req := &acl.ACLPluginGetVersion{}
reply := &acl.ACLPluginGetVersionReply{}

err := ch.SendRequest(req).ReceiveReply(reply)
// process the reply

Note that if the reply message type that comes from VPP does not match with provided one, you'll get an error.

Multipart Reply API

If multiple messages are expected as a reply to a request, SendMultiRequest API must be used:

req := &interfaces.SwInterfaceDump{}
reqCtx := ch.SendMultiRequest(req)

for {
	reply := &interfaces.SwInterfaceDetails{}
	stop, err := reqCtx.ReceiveReply(reply)
	if stop {
		break // break out of the loop
	}
	// process the reply
}

Note that if the last reply has been already consumed, stop boolean return value is set to true. Do not use the message itself if stop is true - it won't be filled with actual data.

Go Channels API

The blocking API introduced above may be not sufficient for some management applications that strongly rely on usage of Go channels. In this case, the API allows to access the underlying Go channels directly, e.g. the following replacement of the SendRequest / ReceiveReply API:

req := &acl.ACLPluginGetVersion{}
// send the request to the request go channel
ch.GetRequestChannel <- &api.VppRequest{Message: req}

// receive a reply from the reply go channel
vppReply := <-ch.GetReplyChannel

// decode the message
reply := &acl.ACLPluginGetVersionReply{}
err := ch.MsgDecoder.DecodeMsg(vppReply.Data, reply)

// process the reply

Notifications API

to subscribe for receiving of the specified notification messages via provided Go channel, use the SubscribeNotification API:

// subscribe for specific notification message
notifChan := make(chan api.Message, 100)
subs, _ := ch.SubscribeNotification(notifChan, interfaces.NewSwInterfaceSetFlags)

// receive one notification
notif := (<-notifChan).(*interfaces.SwInterfaceSetFlags)

ch.UnsubscribeNotification(subs)

Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's buffer is full, the notifications will not be delivered into it.

Index

• Variables
• func SetLogLevel(lvl logger.Level)
• func SetLogger(l *logger.Logger)
• type Channel
  • func (ch *Channel) Close()
  • func (ch *Channel) GetID() uint16
  • func (ch *Channel) SendMultiRequest(msg api.Message) api.MultiRequestCtx
  • func (ch *Channel) SendRequest(msg api.Message) api.RequestCtx
  • func (ch *Channel) SetReplyTimeout(timeout time.Duration)
  • func (ch *Channel) SubscribeNotification(notifChan chan api.Message, event api.Message) (api.SubscriptionCtx, error)
• type Connection
  • func AsyncConnect(vppAdapter adapter.VppAdapter) (*Connection, chan ConnectionEvent, error)
  • func Connect(vppAdapter adapter.VppAdapter) (*Connection, error)
  • func (c *Connection) Disconnect()
  • func (c *Connection) GetMessageID(msg api.Message) (uint16, error)
  • func (c *Connection) LookupByID(msgID uint16) (api.Message, error)
  • func (c *Connection) NewAPIChannel() (api.Channel, error)
  • func (c *Connection) NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (api.Channel, error)
• type ConnectionEvent
• type ConnectionState
• type ControlPing
  • func (*ControlPing) GetCrcString() string
  • func (*ControlPing) GetMessageName() string
  • func (*ControlPing) GetMessageType() api.MessageType
• type ControlPingReply
  • func (*ControlPingReply) GetCrcString() string
  • func (*ControlPingReply) GetMessageName() string
  • func (*ControlPingReply) GetMessageType() api.MessageType
• type MessageCodec
• type MessageIdentifier

Variables

var (
	RequestChanBufSize      = 100 // default size of the request channel buffer
	ReplyChanBufSize        = 100 // default size of the reply channel buffer
	NotificationChanBufSize = 100 // default size of the notification channel buffer
)

var (
	HealthCheckProbeInterval = time.Second * 1        // default health check probe interval
	HealthCheckReplyTimeout  = time.Millisecond * 100 // timeout for reply to a health check probe
	HealthCheckThreshold     = 1                      // number of failed health checks until the error is reported
	DefaultReplyTimeout      = time.Second * 1        // default timeout for replies from VPP
)

var (
	ErrNotConnected = errors.New("not connected to VPP, ignoring the request")
	ErrProbeTimeout = errors.New("probe reply not received within timeout period")
)

var (
	ErrInvalidRequestCtx = errors.New("invalid request context")
)

Functions

func SetLogLevel

func SetLogLevel(lvl logger.Level)

SetLogLevel sets global logger level to lvl.

func SetLogger

func SetLogger(l *logger.Logger)

SetLogger sets global logger to l.

Types

type Channel

type Channel struct {
	// contains filtered or unexported fields
}

channel is the main communication interface with govpp core. It contains four Go channels, one for sending the requests to VPP, one for receiving the replies from it and the same set for notifications. The user can access the Go channels via methods provided by Channel interface in this package. Do not use the same channel from multiple goroutines concurrently, otherwise the responses could mix! Use multiple channels instead.

func (*Channel) Close

func (ch *Channel) Close()

func (*Channel) GetID

func (ch *Channel) GetID() uint16

func (*Channel) SendMultiRequest

func (ch *Channel) SendMultiRequest(msg api.Message) api.MultiRequestCtx

func (*Channel) SendRequest

func (ch *Channel) SendRequest(msg api.Message) api.RequestCtx

func (*Channel) SetReplyTimeout

func (ch *Channel) SetReplyTimeout(timeout time.Duration)

func (*Channel) SubscribeNotification

func (ch *Channel) SubscribeNotification(notifChan chan api.Message, event api.Message) (api.SubscriptionCtx, error)

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a shared memory connection to VPP via vppAdapter.

func AsyncConnect

func AsyncConnect(vppAdapter adapter.VppAdapter) (*Connection, chan ConnectionEvent, error)

AsyncConnect asynchronously connects to VPP using specified VPP adapter and returns the connection handle and ConnectionState channel. This call does not block until connection is established, it returns immediately. The caller is supposed to watch the returned ConnectionState channel for Connected/Disconnected events. In case of disconnect, the library will asynchronously try to reconnect.

func Connect

func Connect(vppAdapter adapter.VppAdapter) (*Connection, error)

Connect connects to VPP using specified VPP adapter and returns the connection handle. This call blocks until VPP is connected, or an error occurs. Only one connection attempt will be performed.

func (*Connection) Disconnect

func (c *Connection) Disconnect()

Disconnect disconnects from VPP and releases all connection-related resources.

func (*Connection) GetMessageID

func (c *Connection) GetMessageID(msg api.Message) (uint16, error)

GetMessageID returns message identifier of given API message.

func (*Connection) LookupByID

func (c *Connection) LookupByID(msgID uint16) (api.Message, error)

LookupByID looks up message name and crc by ID.

func (*Connection) NewAPIChannel

func (c *Connection) NewAPIChannel() (api.Channel, error)

func (*Connection) NewAPIChannelBuffered

func (c *Connection) NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (api.Channel, error)

type ConnectionEvent

type ConnectionEvent struct {
	// Timestamp holds the time when the event has been created.
	Timestamp time.Time

	// State holds the new state of the connection at the time when the event has been created.
	State ConnectionState

	// Error holds error if any encountered.
	Error error
}

ConnectionEvent is a notification about change in the VPP connection state.

type ConnectionState

type ConnectionState int

ConnectionState represents the current state of the connection to VPP.

const (
	// Connected represents state in which the connection has been successfully established.
	Connected ConnectionState = iota

	// Disconnected represents state in which the connection has been dropped.
	Disconnected
)

type ControlPing

type ControlPing struct{}

func (*ControlPing) GetCrcString

func (*ControlPing) GetCrcString() string

func (*ControlPing) GetMessageName

func (*ControlPing) GetMessageName() string

func (*ControlPing) GetMessageType

func (*ControlPing) GetMessageType() api.MessageType

type ControlPingReply

type ControlPingReply struct {
	Retval      int32
	ClientIndex uint32
	VpePID      uint32
}

func (*ControlPingReply) GetCrcString

func (*ControlPingReply) GetCrcString() string

func (*ControlPingReply) GetMessageName

func (*ControlPingReply) GetMessageName() string

func (*ControlPingReply) GetMessageType

func (*ControlPingReply) GetMessageType() api.MessageType

type MessageCodec

type MessageCodec interface {
	//EncodeMsg encodes message into binary data.
	EncodeMsg(msg api.Message, msgID uint16) ([]byte, error)
	// DecodeMsg decodes binary-encoded data of a message into provided Message structure.
	DecodeMsg(data []byte, msg api.Message) error
}

MessageCodec provides functionality for decoding binary data to generated API messages.

type MessageIdentifier

type MessageIdentifier interface {
	// GetMessageID returns message identifier of given API message.
	GetMessageID(msg api.Message) (uint16, error)
	// LookupByID looks up message name and crc by ID
	LookupByID(msgID uint16) (api.Message, error)
}

MessageIdentifier provides identification of generated API messages.