X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=api%2Fapi.go;h=39fe60f0c32a42e2af1c75ddbf5291779d870d20;hb=a3bb834db727a3ac9a1ffcfeae9265e5dead851f;hp=afaa8ad1e8137a474f691b330d78bc215f5d72fa;hpb=2d07847237e754d9050f06f565baa430c70ed937;p=govpp.git diff --git a/api/api.go b/api/api.go index afaa8ad..39fe60f 100644 --- a/api/api.go +++ b/api/api.go @@ -15,12 +15,15 @@ package api import ( - "errors" "fmt" "time" ) // MessageType represents the type of a VPP message. +// Note: this is currently derived from the message header (fields), +// and in many cases it does not represent the actual type of VPP message. +// This means that some replies can be identified as requests, etc. +// TODO: use services to identify type of message type MessageType int const ( @@ -28,7 +31,9 @@ const ( RequestMessage MessageType = iota // ReplyMessage represents a VPP reply message ReplyMessage - // OtherMessage represents other VPP message (e.g. counters) + // EventMessage represents a VPP event message + EventMessage + // OtherMessage represents other VPP message OtherMessage ) @@ -37,11 +42,11 @@ type Message interface { // GetMessageName returns the original VPP name of the message, as defined in the VPP API. GetMessageName() string - // GetMessageType returns the type of the VPP message. - GetMessageType() MessageType - // GetCrcString returns the string with CRC checksum of the message definition (the string represents a hexadecimal number). GetCrcString() string + + // GetMessageType returns the type of the VPP message. + GetMessageType() MessageType } // DataType is an interface that is implemented by all VPP Binary API data types by the binapi_generator. @@ -53,17 +58,6 @@ type DataType interface { GetCrcString() string } -// ChannelProvider provides the communication channel with govpp core. -type ChannelProvider interface { - // NewAPIChannel returns a new channel for communication with VPP via govpp core. - // It uses default buffer sizes for the request and reply Go channels. - NewAPIChannel() (*Channel, error) - - // NewAPIChannel returns a new channel for communication with VPP via govpp core. - // It allows to specify custom buffer sizes for the request and reply Go channels. - NewAPIChannelBuffered() (*Channel, error) -} - // MessageDecoder provides functionality for decoding binary data to generated API messages. type MessageDecoder interface { // DecodeMsg decodes binary-encoded data of a message into provided Message structure. @@ -74,209 +68,86 @@ type MessageDecoder interface { type MessageIdentifier interface { // GetMessageID returns message identifier of given API message. GetMessageID(msg Message) (uint16, error) -} -// Channel is the main communication interface with govpp core. It contains two Go channels, one for sending the requests -// to VPP and one for receiving the replies from it. The user can access the Go channels directly, or use the helper -// methods provided inside of this package. Do not use the same channel from multiple goroutines concurrently, -// otherwise the responses could mix! Use multiple channels instead. -type Channel struct { - ReqChan chan *VppRequest // channel for sending the requests to VPP, closing this channel releases all resources in the ChannelProvider - ReplyChan chan *VppReply // channel where VPP replies are delivered to - - NotifSubsChan chan *NotifSubscribeRequest // channel for sending notification subscribe requests - NotifSubsReplyChan chan error // channel where replies to notification subscribe requests are delivered to - - MsgDecoder MessageDecoder // used to decode binary data to generated API messages - MsgIdentifier MessageIdentifier // used to retrieve message ID of a message - - replyTimeout time.Duration // maximum time that the API waits for a reply from VPP before returning an error, can be set with SetReplyTimeout - metadata interface{} // opaque metadata of the API channel -} - -// VppRequest is a request that will be sent to VPP. -type VppRequest struct { - Message Message // binary API message to be send to VPP - Multipart bool // true if multipart response is expected, false otherwise -} - -// VppReply is a reply received from VPP. -type VppReply struct { - MessageID uint16 // ID of the message - Data []byte // encoded data with the message - MessageDecoder can be used for decoding - LastReplyReceived bool // in case of multipart replies, true if the last reply has been already received and this one should be ignored - Error error // in case of error, data is nil and this member contains error description -} - -// NotifSubscribeRequest is a request to subscribe for delivery of specific notification messages. -type NotifSubscribeRequest struct { - Subscription *NotifSubscription // subscription details - Subscribe bool // true if this is a request to subscribe, false if unsubscribe -} - -// NotifSubscription represents a subscription for delivery of specific notification messages. -type NotifSubscription struct { - NotifChan chan Message // channel where notification messages will be delivered to - MsgFactory func() Message // function that returns a new instance of the specific message that is expected as a notification + // LookupByID looks up message name and crc by ID + LookupByID(msgID uint16) (Message, error) } -// RequestCtx is a context of a ongoing request (simple one - only one response is expected). -type RequestCtx struct { - ch *Channel -} - -// MultiRequestCtx is a context of a ongoing multipart request (multiple responses are expected). -type MultiRequestCtx struct { - ch *Channel -} - -const defaultReplyTimeout = time.Second * 1 // default timeout for replies from VPP, can be changed with SetReplyTimeout +// ChannelProvider provides the communication channel with govpp core. +type ChannelProvider interface { + // NewAPIChannel returns a new channel for communication with VPP via govpp core. + // It uses default buffer sizes for the request and reply Go channels. + NewAPIChannel() (Channel, error) -// NewChannelInternal returns a new channel structure with metadata field filled in with the provided argument. -// Note that this is just a raw channel not yet connected to VPP, it is not intended to be used directly. -// Use ChannelProvider to get an API channel ready for communication with VPP. -func NewChannelInternal(metadata interface{}) *Channel { - return &Channel{ - replyTimeout: defaultReplyTimeout, - metadata: metadata, - } + // NewAPIChannelBuffered returns a new channel for communication with VPP via govpp core. + // It allows to specify custom buffer sizes for the request and reply Go channels. + NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error) } -// Metadata returns the metadata stored within the channel structure by the NewChannelInternal call. -func (ch *Channel) Metadata() interface{} { - return ch.metadata -} +// Channel provides methods for direct communication with VPP channel. +type Channel interface { + // GetID returns channel's ID + GetID() uint16 -// SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply -// from VPP before returning an error. -func (ch *Channel) SetReplyTimeout(timeout time.Duration) { - ch.replyTimeout = timeout -} + // SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply. + // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply). + SendRequest(msg Message) RequestCtx -// Close closes the API channel and releases all API channel-related resources in the ChannelProvider. -func (ch *Channel) Close() { - if ch.ReqChan != nil { - close(ch.ReqChan) - } -} + // SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP. + // Returns a multipart request context, that can be used to call ReceiveReply. + // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply). + SendMultiRequest(msg Message) MultiRequestCtx -// SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply. -// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply). -func (ch *Channel) SendRequest(msg Message) *RequestCtx { - ch.ReqChan <- &VppRequest{ - Message: msg, - } - return &RequestCtx{ch: ch} -} + // SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel. + // 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. + SubscribeNotification(notifChan chan Message, msgFactory func() Message) (*NotifSubscription, error) -// ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). -// The reply will be decoded into the msg argument. Error will be returned if the response cannot be received or decoded. -func (req *RequestCtx) ReceiveReply(msg Message) error { - if req == nil || req.ch == nil { - return errors.New("invalid request context") - } + // UnsubscribeNotification unsubscribes from receiving the notifications tied to the provided notification subscription. + UnsubscribeNotification(subscription *NotifSubscription) error - lastReplyReceived, err := req.ch.receiveReplyInternal(msg) + // SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply + // from VPP before returning an error. + SetReplyTimeout(timeout time.Duration) - if lastReplyReceived { - err = errors.New("multipart reply recieved while a simple reply expected") - } - return err + // Close closes the API channel and releases all API channel-related resources in the ChannelProvider. + Close() } -// SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP. -// Returns a multipart request context, that can be used to call ReceiveReply. -// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply). -func (ch *Channel) SendMultiRequest(msg Message) *MultiRequestCtx { - ch.ReqChan <- &VppRequest{ - Message: msg, - Multipart: true, - } - return &MultiRequestCtx{ch: ch} +// RequestCtx is helper interface which allows to receive reply on request context data +type RequestCtx interface { + // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). + // The reply will be decoded into the msg argument. Error will be returned if the response cannot be received or decoded. + ReceiveReply(msg Message) error } -// ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). -// The reply will be decoded into the msg argument. If the last reply has been already consumed, LastReplyReceived is -// set to true. Do not use the message itself if LastReplyReceived is true - it won't be filled with actual data. -// Error will be returned if the response cannot be received or decoded. -func (req *MultiRequestCtx) ReceiveReply(msg Message) (LastReplyReceived bool, err error) { - if req == nil || req.ch == nil { - return false, errors.New("invalid request context") - } - - return req.ch.receiveReplyInternal(msg) +// MultiRequestCtx is helper interface which allows to receive reply on multi-request context data +type MultiRequestCtx interface { + // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). + // The reply will be decoded into the msg argument. If the last reply has been already consumed, lastReplyReceived is + // set to true. Do not use the message itself if lastReplyReceived is true - it won't be filled with actual data. + // Error will be returned if the response cannot be received or decoded. + ReceiveReply(msg Message) (lastReplyReceived bool, err error) } -// receiveReplyInternal receives a reply from the reply channel into the provided msg structure. -func (ch *Channel) receiveReplyInternal(msg Message) (LastReplyReceived bool, err error) { - if msg == nil { - return false, errors.New("nil message passed in") - } - select { - // blocks until a reply comes to ReplyChan or until timeout expires - case vppReply := <-ch.ReplyChan: - if vppReply.Error != nil { - err = vppReply.Error - return - } - if vppReply.LastReplyReceived { - LastReplyReceived = true - return - } - // message checks - expMsgID, err := ch.MsgIdentifier.GetMessageID(msg) - if err != nil { - err = fmt.Errorf("message %s with CRC %s is not compatible with the VPP we are connected to", - msg.GetMessageName(), msg.GetCrcString()) - return false, err - } - if vppReply.MessageID != expMsgID { - err = fmt.Errorf("invalid message ID %d, expected %d "+ - "(also check if multiple goroutines are not sharing one GoVPP channel)", vppReply.MessageID, expMsgID) - return false, err - } - // decode the message - err = ch.MsgDecoder.DecodeMsg(vppReply.Data, msg) - - case <-time.After(ch.replyTimeout): - err = fmt.Errorf("no reply received within the timeout period %ds", ch.replyTimeout/time.Second) - } - return +// NotifSubscription represents a subscription for delivery of specific notification messages. +type NotifSubscription struct { + NotifChan chan Message // channel where notification messages will be delivered to + MsgFactory func() Message // function that returns a new instance of the specific message that is expected as a notification + // TODO: use Message directly here, not a factory, eliminating need to allocation } -// SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel. -// 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. -func (ch *Channel) SubscribeNotification(notifChan chan Message, msgFactory func() Message) (*NotifSubscription, error) { - subscription := &NotifSubscription{ - NotifChan: notifChan, - MsgFactory: msgFactory, - } - ch.NotifSubsChan <- &NotifSubscribeRequest{ - Subscription: subscription, - Subscribe: true, - } - return subscription, <-ch.NotifSubsReplyChan -} +var registeredMessages = make(map[string]Message) -// UnsubscribeNotification unsubscribes from receiving the notifications tied to the provided notification subscription. -func (ch *Channel) UnsubscribeNotification(subscription *NotifSubscription) error { - ch.NotifSubsChan <- &NotifSubscribeRequest{ - Subscription: subscription, - Subscribe: false, +// RegisterMessage is called from generated code to register message. +func RegisterMessage(x Message, name string) { + if _, ok := registeredMessages[name]; ok { + panic(fmt.Errorf("govpp: duplicate message registered: %s (%s)", name, x.GetCrcString())) } - return <-ch.NotifSubsReplyChan + registeredMessages[name] = x } -// CheckMessageCompatibility checks whether provided messages are compatible with the version of VPP -// which the library is connected to. -func (ch *Channel) CheckMessageCompatibility(messages ...Message) error { - for _, msg := range messages { - _, err := ch.MsgIdentifier.GetMessageID(msg) - if err != nil { - return fmt.Errorf("message %s with CRC %s is not compatible with the VPP we are connected to", - msg.GetMessageName(), msg.GetCrcString()) - } - } - return nil +// GetAllMessages returns list of all registered messages. +func GetAllMessages() map[string]Message { + return registeredMessages }